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

With annotations already declaring readOnlyHint=false and destructiveHint=false, the description goes well past them: it explains the gating rule (start returns go:false if a run is going or within 10 minutes of its planned end), how freeapply_clear_to_submit with run_id terminates a run, that finish releases the run and is harmless when repeated, the exact return shapes for each action, and the two error cases. This is the full behavioral burden discharged.

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, then labeled sections (Behavior, Parameters, Returns, Errors) keep the dense content navigable. It is long and information-dense — near the upper limit for a single tool description — but almost every clause is load-bearing 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?

A four-action tool with no output schema and cross-tool coupling to freeapply_clear_to_submit; the description covers returns for each action, the go:false reason categories, error conditions, and the call-site contract. 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?

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: run_id must be the value start returned, summary is "one line on the run" capped at 500 characters, and action is framed as the step selector whose effects vary per enum value. The 500-character limit and the required pairing of run_id with finish are details the schema does not 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 pair and resource ("Starts and finishes unattended (scheduled) runs, and records the schedule") and explicitly distinguishes itself from freeapply_status by noting that status only shows run state while this changes it. An agent can tell which tool to pick 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 for each action (start at the beginning of every scheduled run, finish at its end including early stops, schedule_created/schedule_removed after creating or deleting the scheduled task) and an explicit exclusion ("Not in a session the user runs by hand"), plus the named alternative freeapply_status. 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?

The description adds substantial behavior beyond the annotations: without save nothing changes, with save a passing letter becomes a PDF, a failing one is never saved, saving again replaces the file, and a job already applied to is refused. It also explains unsupported claims, error cases, and the résumé-unsaved edge case. This does not contradict the annotations; it enriches them.

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

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

The description is long but front-loaded and structured as purpose, usage, behavior, parameters, returns, and errors. Every sentence contributes operational detail, including edge cases and return shapes, because no output schema exists. There is little redundancy despite the density.

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 no output schema, the description supplies the return shape {ok, problems} and conditional keywords/file data. It covers save behavior, error conditions, prerequisite risks around an unsaved résumé, and parameter-specific checks. Nothing essential for correct invocation 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?

Although schema coverage is 100%, the description adds real meaning beyond the schema: kind cover_letter also checks length, sign-off, placeholders, and employer naming, while answer checks facts only. It explains that job_id adds posting keywords and is needed for save, and that company names the employer when job_id is absent. It also advises passing save from the first call for letters.

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 and resource: checking a cover letter or free-text answer and turning a passing cover letter into a PDF. It explicitly distinguishes itself from freeapply_update_job by saying that sibling only records the result, while this tool is where prose is checked. An agent can identify the tool without opening the 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: use before typing any written answer or attaching any letter, and again after each fix. It also states an exclusion: not for short fields taken straight from settings, such as name, date, or yes/no. The alternative freeapply_update_job is named and contrasted.

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 explaining duplicate handling, site eligibility checks, repost detection, pay-floor skipping, return fields, and errors. Annotations already cover the safety profile, but the description still adds substantial behavioral context about ordering and side effects.

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 organizes behavior, parameters, returns, and errors into clear labeled sections. It is dense and somewhat long, but most sentences carry operational value for a complex mutation 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?

No output schema exists, but the description documents the return shape and the earlier list. Given the 16-parameter schema, annotations, and behavioral complexity, it provides enough context for an agent to call the 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?

Schema coverage is 100%, so the baseline is 3; the description adds meaningful semantics for key parameters such as company vs. staffing firm, external_id for reposts, url/source for site origin, pay_min/pay_max feeding the pay floor, and fit_score range. It does not explain every one of the 16 parameters, but it adds useful meaning beyond the already-rich 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 action and resource: claims a job, runs duplicate checks, applies rules, starts tracking, and returns job_id. It explicitly distinguishes itself from freeapply_list_jobs and freeapply_update_job, so an agent can select it correctly.

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 guidance: before opening any application form, and for recording skipped jobs. It also states when not to use it—'Not for changing a job you already claimed'—and names the relevant alternative behavior.

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?

Discloses important stateful behavior beyond annotations: per-minute pace, daily cap, one-click apply restriction, 15-minute clearance lifetime, single-use clearance consumed by update_job, and that new requests issue new clearances. It also explains that clearances only last while FreeApply runs and what run_id budget/Stop checks imply.

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

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

The description is dense but appropriately sized for a stateful, policy-driven tool. It is front-loaded with purpose and sibling contrast, then proceeds through usage, behavior, parameters, and return/action handling without wasted sentences.

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?

Although there is no output schema, the description explains the return fields and how to interpret clear false, refused, and stop_run true. Combined with the schema and annotations, it gives an agent enough information to invoke and react to the 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?

Even though schema description coverage is 100%, the description adds meaningful semantics: job_id is what gets the clearance and without it only the pace is shown; method defaults to external and matters only for easy_apply; run_id is for unattended runs and triggers budget and Stop-button checks.

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: gives clearance to submit one job right before submission. It explicitly distinguishes itself from freeapply_update_job by explaining that update_job records the submit afterwards and is refused 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?

Gives explicit timing guidance: use right before every submit with job_id, not early, and not for a job you will not submit now. It also explains what to do when clear is false, when refused due to one-click apply being off, and when stop_run is true with a required follow-up call.

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 disclosing per-site API vs page-text behavior, the SSRF-style refusal of local/private addresses and redirects, and session-level caching that freeapply_claim_job depends on. Annotations already cover read-only/idempotent, so this adds real operational context; error handling is summarized but retry semantics for transient failures are not spelled out.

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

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

Front-loaded purpose, then usage, behavior, parameters, returns, errors, and next step — a clean, scannable structure. Slightly dense in the params/returns sentences, but nearly every clause 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?

Even without an output schema, the description enumerates the returned fields including the keywords {matched, missing, coverage} triple and the guidance not to claim missing skills. Errors and the follow-up tool are covered, so an agent can invoke and act on the result without guessing.

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 adds meaning the schema lacks, such as max_chars capping only the description, description_chars reporting full length, and source selecting site-specific saved answers. That is genuine value beyond the schema text.

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') and immediately scopes it: trimmed, with form questions, suggested answers, and required skills. It explicitly contrasts with the browser alternative and with search-results pages, so an agent can distinguish it from siblings like freeapply_list_jobs.

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 before scoring or applying') and when-not ('not for search-results pages or pages behind a sign-in; read those in the browser'). It also names the next tool in the workflow (freeapply_claim_job), giving a complete routing decision.

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, but the description adds substantial context beyond them: no passwords are stored, the user records accounts on the dashboard, and the returned states imply concrete next actions. It also documents the error case for inputs that are not domains or URLs.

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 purpose, then sibling differentiation, usage guidance, behavior, parameter semantics, return shape, and errors. Despite its length, each section carries operational value for a one-parameter tool that drives a multi-step account workflow.

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 return shape for both known and unknown accounts. It also explains the actions to take in each case and the error condition, leaving no major ambiguity 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 100%, so the schema already documents the site parameter. The description adds important matching semantics: www is stripped, matching is exact, and subdomains such as careers.example.com are treated as distinct from example.com.

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: looking up whether the user already has an employer-site account and which email was used. It explicitly distinguishes this from freeapply_report_site_problem, which handles job-board sign-outs rather than employer sites.

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 a clear trigger: use when an application form asks the agent to sign in or create an account. It also gives an explicit exclusion: this is not for signing in or up, because FreeApply never stores passwords, and it names the alternative tool for a related but different scenario.

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, yet the description still adds value beyond them: installation secrets are never included, the return shape is {settings, missing}, and `missing` acts as a blocking precondition. It also discloses the error case (unknown section name, message lists valid ones) and a guardrail against fabricating user facts.

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 labeled Behavior/Parameters/Returns/Errors, and nearly every sentence carries actionable content. It is, however, a dense paragraph with deeply nested parentheticals (the long section enumeration) that would scan faster as a list; slight tightening is possible without losing 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 and only one optional parameter, the description compensates fully: it enumerates the returned sections and their contents, explains `missing`, describes the error path, and states the session-level calling convention. Nothing an agent needs to invoke or 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 100%, so baseline would be 3, but the description adds real meaning: `sections` narrows the reply to what a step needs, is illustrated with a concrete example (["profile", "eligibility"] for a form), defaults to all, and warns that resume is the largest and should be omitted when its text isn't needed — a cost hint the schema lacks.

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 ("Reads the user's settings") and immediately scopes it: identity, targets, and FreeApply behavior. It explicitly names the two nearest siblings (freeapply_user_answers and freeapply_status) and states how this differs from each, so an agent can select it 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 concrete when-to-use ("once per session, or once per helper, before scoring jobs or filling in a form") plus the exclusion and alternative ("To change settings, use freeapply_update_settings"). It also adds a gated follow-up path: while `missing` is non-empty, open the dashboard and ask the user, rather than proceeding.

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?

Although annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, the description adds genuinely non-redundant behavior: counts are computed fresh from the local database on every call with no caching, and the tool takes no parameters. It also clarifies a non-obvious semantic ('response_rate' counts only real replies, not automatic acknowledgements) and defines 'needs_you' and '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?

The text is front-loaded with purpose and disambiguation before the behavior and return-value blocks, and each section is scannable. The long enumeration of return fields is justified because no output schema exists, though it is dense and could be grouped more tightly.

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 carries the burden of describing returns, and it does so exhaustively across scalars, rate definitions, by_status/by_outcome/by_method groupings, daily series, and top_companies/top_titles/top_jobs. Combined with the read-only annotation profile, an agent has everything needed to call and interpret this 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?

With zero parameters, the baseline is 4, and the description does confirm 'Takes no parameters', removing any ambiguity about whether filters or date ranges exist. There is no further parameter meaning to convey, so it cannot exceed the baseline meaningfully.

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: 'Summarizes the user's job search in numbers', then enumerates the concrete metrics (applications, replies, interviews, offers, rates). It explicitly distinguishes itself from freeapply_list_jobs (individual jobs) and freeapply_status (whether FreeApply can run), so an agent can route correctly 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 both a positive trigger ('Use it to report progress, for example when wrapping up a session') and a negative exclusion ('Not for finding a particular job'), plus named alternatives for the excluded case. Nothing about when to choose this tool 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 mark this as read-only, idempotent, non-destructive, and closed-world. The description adds useful behavioral detail beyond that: sorting order, exact-match filters, case-insensitive search, pagination behavior, and end-of-list detection.

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 purpose and alternatives, then moves efficiently through behavior, parameters, and returns. The return-field list is long but justified 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?

With no output schema and five optional parameters, the description supplies the missing context: use cases, sibling alternatives, filtering semantics, pagination behavior, and returned fields. An agent has enough information to select and 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?

Schema coverage is 100%, so the schema already documents each parameter. The description still adds meaning by explaining that filters combine, status and outcome match exactly, search covers title/company/location ignoring case, and pagination works through limit and offset.

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: it lists the user's tracked jobs. It explicitly distinguishes itself from freeapply_job_stats by explaining that it returns the jobs themselves rather than totals and rates.

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 use cases: find a job_id or answer questions about particular jobs. It also states what it is not for, pointing adding or changing jobs to freeapply_claim_job and 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?

Annotations already establish read-only, idempotent, non-destructive, non-open-world behavior. The description adds useful context beyond that: it starts the dashboard if needed, uses localhost on port 7878 or the next free port, is reachable only from this computer, and changes no data.

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 action and the sibling distinction, then cleanly sections usage, behavior, parameters, and returns. Despite its length, every section carries operational value for correct invocation.

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

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

There is no output schema, but the description explains the {url, opened} return shape and both failure modes: null url when the dashboard cannot start, and false opened with a url when no browser could be launched. That is enough for an agent to act 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 documents the tab parameter and enum values, but the description adds meaningful semantics for each tab: overview shows Terms until accepted, settings shows setup fields, issues shows the Needs list, and applications/replies are review tabs. This materially improves selection beyond the raw enum names.

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: opening the user's local FreeApply dashboard in their browser. It explicitly distinguishes itself from freeapply_status, which only reports the address, so the agent can choose between them without inspecting schemas.

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

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

Gives explicit when-to-use guidance: when the user must accept Terms, fill settings, answer waiting questions, or review applications and replies. It also gives a clear when-not-to-use rule: not for reading data because other tools provide the same information.

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 past the annotations: it discloses the rank-based raise-only rule with an email, exact-set semantics without one, deduplication of a repeated gmail_message_id, the clearing behavior of an empty outcome, and enumerated error conditions. It is consistent with idempotentHint=true and non-destructive framing.

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

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

Front-loads purpose, then behavior, parameters, returns, and errors in a predictable order with no filler sentences. It is dense and long, but nearly every clause carries conditional or semantic 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?

For a 10-parameter mutation tool with no output schema, it supplies the return shapes for both branches and the error cases, so an agent can call it and interpret the result without inference. Nothing material 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 already 100%, but the description adds conditional logic the schema cannot express: job_id is required without an email but optional (and outcome-inert) with one, and empty outcome is only valid without an email. It also supplies the mail_action value vocabulary and a 20-word/no-PII constraint on summary that the schema omits.

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 ('Records what an employer did with an application') and enumerates the exact outcome space. It explicitly contrasts with freeapply_update_job (employer's response vs. your own side), making it distinguishable from the closest sibling 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?

States concrete triggers (each employer email found during a reply check, between freeapply_reply_check start and finish, when the user reports a call or corrects an outcome) and an explicit exclusion ('Not for your own steps'), pointing at the sibling that covers that case.

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 behavior beyond the annotations: start is read-only and repeatable, while finish sets the last check time and changes what the next check searches. It also warns to call finish only after recording everything found, which is important operational context not captured by the schema or 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 description is front-loaded and organized into purpose, usage, behavior, parameters, returns, and errors. It is somewhat repetitive in restating start/finish behavior across sections, but the repetition reinforces a short two-action workflow rather than adding noise.

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 workflow tool with no output schema, the description covers the missing return-value information directly, including the plan returned by start and {last_check} returned by finish. It also explains the key side effect of finish and the error case, leaving no important gap 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 coverage is 100% and the enum already documents start/finish, but the description goes further by explaining what start returns: since, gmail, applied, and known_message_ids. It adds meaningful semantics for the action parameter beyond the schema, though the parameter itself is simple.

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 uses a specific verb+resource+workflow framing: it begins/ends a Gmail reply check and explicitly distinguishes this framing role from freeapply_record_outcome, which records individual emails. An agent can tell exactly what the tool is for and what it is not for.

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 ordering and conditions: use start before searching Gmail, use finish only after every found email is recorded, and do not use this tool for recording an email. It also names the sibling alternative freeapply_record_outcome, so the routing decision 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?

Goes well past the annotations: describes the downstream effect on freeapply_claim_job (refuses new jobs from the reported site), the duration of each state (signed-out until user re-confirms in dashboard; limit paused until midnight), idempotency in plain terms ('reporting the same problem again changes nothing'), and who can reverse it ('only the user can mark a site ready'). This explains the destructiveHint consequence better than the annotation alone does.

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 purpose and the sibling contrast, then organized into Behavior / Parameters / Returns / Errors blocks. Dense but every line carries information; the Returns and Errors lines could be folded in more tightly, 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, so the description supplies the return shape ({site, status, sites} with ready flags) and an error case (a site the user didn't choose). Combined with the state/pause semantics, 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 100% and both params are enums, so the baseline is 3; the description adds real meaning by interpreting each status value with examples ('a sign-in page', '"You reached today's Easy Apply limit"') and by tying site to the ids listed in freeapply_status. Slight over-reliance on the schema for the site enumeration itself.

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 (tells FreeApply a chosen job site can't be used, signed out or limit reached) and explicitly contrasts itself with the sibling freeapply_find_site_account (employer careers site vs. user-chosen sites like LinkedIn/Indeed). An agent can route between the two 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 a concrete trigger ('as soon as a chosen job site shows a sign-in page or a daily limit'), a fallback plan ('keep applying on the ready sites or on company career sites'), and a hard exclusion ('never type a password'). The distinction from freeapply_find_site_account is spelled out 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?

Goes well past the annotations: preview is read-only and sends nothing, sync reaches the internet and cannot be undone from here, it also fires automatically every 12 hours, and sync is refused moments after the last sync. Return shapes and failure reasons (Terms not accepted, recent sync, server unreachable) are spelled out, consistent with openWorldHint=true and destructiveHint=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-loaded with purpose, then labeled Behavior/Parameters/Returns/Errors sections that make scanning easy. Slightly redundant: the preview-vs-sync distinction is restated in the Parameters block after already appearing in the usage paragraph.

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 both return shapes (analytics_request and talent-pool request for preview; {sent, result} or {sent: false, reason} for sync) and enumerates the refusal reasons. For a one-parameter tool with a network side effect, nothing material 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% and the enum already names both values, so the baseline is 3. The description adds real per-value semantics — preview safe any time, sync sends now and may be rejected right after a prior sync — rather than restating the enum.

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 (shows/preview vs sends/sync) and the exact resource (the data the user chose to share with the FreeApply server). It explicitly distinguishes itself from the nearest sibling, freeapply_get_settings: choices vs. the exact data those choices send.

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

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

Gives a direct routing rule — 'Use preview when the user asks what is shared, and sync only when the user asks to send now' — plus an exclusion ('Not for changing the choices: the user does that in the dashboard') and an alternative surface (Settings, Data sharing). 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?

Goes well beyond the readOnly/idempotent/non-destructive annotations by disclosing side effects an agent would otherwise not expect: creating the data folder on first run, starting the local dashboard, and refreshing the résumé copy. It also documents the failure semantics (works while locked, reports why) rather than hiding them. Only mild tension exists between readOnlyHint and those setup side effects, but the description surfaces them openly rather than concealing them.

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

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

Well front-loaded — purpose first, then sibling contrast, then usage, then Behavior/Parameters/Returns/Next sections, making it easy to scan. It is on the long side, though: the full enumeration of models {can_delegate, rescan, levels, lanes, unfilled} and per-lane {model, effort, source} is heavier detail than most invocations need.

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 enumerating the returned fields, calling out the conditional procedure payload and its null-while-locked behavior, and giving error-handling next steps. For a status-plus-procedure gate tool with 17 siblings, nothing an agent needs in order 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 already 100% with an enum, yet the description adds selection logic the enum values alone do not convey: freeapply-setup for first run or missing Terms/settings, freeapply-apply for finding and applying to jobs, freeapply-replies for the Gmail reply check, and 'omit it for the status alone'. This is real added meaning over 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 ('Reports whether FreeApply can work now and returns the signed step-by-step procedure for a task') and explicitly distinguishes itself from the two nearest siblings: freeapply_get_settings (user details) and freeapply_job_stats (job search). An agent can route to it 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 explicit timing rules ('Use it first in every session and before each task; call it again only to re-check after the user acts'), an edge-case guarantee (works while locked or Terms not accepted), and concrete branching in 'Next' for workflow.ok false and terms.ok/setup_complete false. Both when-to-use and what-to-do-next are spelled out.

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 (destructive, idempotent, non-read-only) by disclosing enforcement rules: applied requires fresh clearance from freeapply_clear_to_submit, cover_text passes truthfulness check, only the user can change an already-applied job, needs_info re-queues the job, and a refusal returns answers when all questions were already answered. These are behavioral traits an agent cannot infer from annotations alone, and none contradict them.

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 long but tightly structured with labeled sections (Behavior, Parameters, Returns, Errors) and the purpose is front-loaded. Nearly every sentence carries actionable information, though the density could be trimmed slightly without loss.

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

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

With 10 parameters and no output schema, the description fills the gap by documenting the return shape ({job_id, status}, already_waiting, questions, same_account, same_site) and error behavior. Together with parameter and behavior sections, an agent has everything needed 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful conditional semantics: which fields pair with which status and are otherwise refused, and that résumé/letter defaults are recorded unless overridden. It also clarifies that 'note' is one plain sentence for the user. This is real value beyond the schema, though some of the field-status coupling is already present in the 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 verb and resource ('Records your side of an application by setting a tracked job's status') and explicitly distinguishes itself from freeapply_record_outcome (employer side) and freeapply_claim_job (adding a job). An agent can identify this as the status-mutation 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?

Explicitly names when to use it: after a submit (applied), when giving up (skipped/failed), and when the user must act (needs_info, needs_account, blocked), plus a clear exclusion ('Not for employer replies'). The status triggers function as concrete invocation 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?

The annotations already mark the tool as destructive and non-read-only, but the description adds crucial behavior: fields are overwritten with no undo, patch is deep-merged, lists are replaced wholesale, dashboard-only sections are skipped and returned in ignored, and the operation is all-or-nothing. It also describes return fields and error cases, giving the agent a full operational picture beyond 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?

Despite its length, the description is front-loaded with purpose, then usage, behavior, parameter details, returns, and errors. Each section carries distinct, necessary information for a complex write operation, and no sentence is redundant 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 complex mutation tool with no output schema, the description covers when to use it, how merging and skipping work, all-or-nothing behavior, return shape, and error conditions. It gives the agent everything needed to invoke the tool correctly and interpret its results.

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

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

Schema coverage is 100%, but the description still adds substantial meaning: patch is nested by section using freeapply_get_settings field names, with a concrete example. It further explains resume's text/profile shape and models' scan shape, including that models replaces the last scan. This goes well beyond the schema's generic patch 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?

The description uses specific verbs and resources: saving settings, résumé setup data, and AI model scan data. It explicitly distinguishes itself from freeapply_user_answers by saying it changes settings themselves rather than single-question answers. An agent can identify the tool's purpose and boundary against siblings 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 gives explicit usage conditions: when the user states a fact or preference, during setup to store résumé text/profile, and in the AI models step. It also gives exclusions and alternatives: do not fill fields the user did not provide, and use freeapply_get_settings to read settings. This is clear when-to-use and when-not-to-use 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 declare destructiveHint=true but say nothing about what is destroyed; the description fills that gap by stating that save replaces an answer under the same question and that an empty answer removes it, plus that get is read-only. It also warns that saved answers count as facts in freeapply_check_text, which is non-obvious downstream behavior.

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

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

Front-loaded with purpose and sibling contrast, then organized under Behavior, Parameters, Returns and Errors headings, which makes it easy to scan. It is longer than strictly necessary because the Parameters section restates schema content, but nearly every sentence carries 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 return shapes for both actions (answers vs saved_answers for get, label/saved/removed for save) and enumerates error conditions. For a dual-action tool with conditional parameters, nothing an agent needs in order 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 100% and the schema already documents each parameter including the label example, so the description's 'Parameters:' recap is largely duplicative. It adds only marginal semantics, namely that the answer should be 'the user's own words' and that an empty answer is the removal mechanism.

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 pair and resource ('Gets or saves the user's own answers to application questions') and explicitly contrasts itself with freeapply_get_settings (general details) and freeapply_update_job status needs_info, so an agent can distinguish it from siblings 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?

It gives concrete triggers: use get before retrying a job the user re-queued from the Needs you tab, and save when the user answers a question in this conversation. It also names the two nearest alternatives and states what differs, which is exactly the when/when-not/alternatives pattern.

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