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

Annotations only cover readOnly/idempotent/openWorld hints; the description adds meaningful context they don't: the tool requires a connected AI Applyd account and consumes the user's AI credits, and it explains what is extracted. It stops short of describing pagination, limits, or failures, but for a short analysis call this is strong added value.

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

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

Four tight sentences, each earning its place: what it does, why it matters, a prerequisite/cost note, an exclusion with alternative, and next steps. Information is front-loaded with no filler.

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

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

With an output schema present, return values need not be explained, and the description covers the practical essentials: account/credit requirements, the read-from-link exclusion, and the recommended follow-up tools. Nothing an agent needs to select or call it 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% with a single well-documented 'job_description' parameter, so the schema already carries the semantics. The description adds nothing about length limits or expected format, so the 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?

Specific verb (extract) plus resource (ATS keywords and requirements from a job posting) and it details the output shape (category, importance, must-have flag). It is clearly separable from sibling tools like get_matches and score_resume.

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

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

Explicitly states when-not-to-use ('Do not use it to read a posting from a link; use aiapplyd_get_matches with job_url') and names the alternative. It also spells out the follow-on tools (score_resume/optimize_resume) with the same input, giving a full routing path.

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

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

Annotations already declare destructive/non-idempotent/open-world, and the description adds materially beyond that: it spends an application and AI credits, submitted applications cannot be withdrawn, alreadyExisting applications return with alreadyExisted true instead of duplicating, and the retry protocol on timeout ('call aiapplyd_get_applications before retrying'). These are exactly the consequences an agent must know before acting.

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

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

Front-loaded with the core action, then costs, then recovery guidance, then routing to siblings. It is fairly long and repeats the mode explanation that the schema already carries, but almost every sentence contributes operational value 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?

Despite the return format being covered by an output schema, the description surfaces the important return cases (application id, tracking link, alreadyExisted) and the failure path. For a destructive, credit-consuming, one-shot operation, nothing an agent needs to act safely 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 all three parameters are already documented, including the mode enum and the job_url/job_match_id exclusivity. The description restates the mode behavior and the match-id/url source, adding context but little that isn't already in the schema. Baseline 3 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?

States a specific verb and resource ('Apply to one job on the user's behalf') with the scope ('one job') that implicitly separates it from a bulk apply flow, and names the ATS platforms involved. It does not explicitly name the sibling aiapplyd_auto_apply, which is the closest potential confusion, so differentiation relies partly on inference.

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 input routing (pass job_match_id from aiapplyd_get_matches, or job_url), mode semantics with the account-setting fallback, an explicit exclusion ('Do not use it to save or skip a match; use aiapplyd_triage_matches'), and follow-up tools. An agent has everything needed to choose this tool and invoke it correctly.

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

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

Annotations already declare destructive=true, readOnly=false, idempotent=false, openWorld=true, so the safety profile is covered. The description still adds real context: it applies on the employer's own hiring system, respects the account's review setting, and 'spends one of the user's applications' — a cost/consequence not expressed in any structured field.

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 deprecation notice and the cost statement are correctly front-loaded and earn their place, but the enumeration of ~30 ATS platform names consumes roughly half the text without helping the agent decide or invoke. Trimming the list would sharpen the definition considerably.

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 an output schema present, annotations covering the safety profile, and a single 100%-documented parameter, the description only needed to add deprecation routing, scope, and side effects — all of which it does. Little is missing apart from any hint about failure modes on unsupported employers.

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?

Only one parameter and schema description coverage is 100%, so the schema already documents job_url fully. The description restates that application is keyed by job_url but adds no format, validation, or edge-case detail beyond the schema, which is the baseline-3 case.

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?

Front-loads the deprecation status and the replacement tool by name, then states a specific verb+resource: applies to ONE job posting by job_url, end to end. An agent can distinguish it from aiapplyd_apply and from read-only siblings without opening any schema.

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

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

Explicitly instructs 'use aiapplyd_apply' instead, which is the clearest possible when-to-use / when-not-to-use guidance. It also states the operative condition that the behavior 'follows the account's review setting', so the agent knows the call may not submit immediately.

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 give the generic safety profile (readOnly false, non-destructive, non-idempotent, openWorld). The description adds material traits they don't: a paid-plan requirement, the private-by-default posture, the preview-vs-creation distinction when resume_text is omitted, and the inherent limitation that it will not split text into experience/education/skills sections. These are exactly the behavioral facts an agent needs before invoking 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?

Core purpose is front-loaded and every sentence carries an actionable rule (section limitation, default privacy, plan gate, sibling routing, no-input behavior). It runs long and the optionality of resume_text is effectively stated twice, but nothing is padding in the way of restating the title.

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

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

For a zero-required-parameter mutation tool with an output schema, the description covers the gaps structured fields cannot: prerequisite plan, privacy default, the empty-input fallback return path, and honest scoping of what the tool does not do. An agent has everything needed to decide whether to call it and what to expect.

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, and the description stays mostly within what the schema already states for template and make_public. It does add one genuinely new constraint not present in the schema – resume_text is funneled into a summary section capped at 2,000 characters – which meaningfully shapes how an agent should call the tool.

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

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

States a specific verb and resource ('Create an editable resume draft') and immediately clarifies the tool's dual nature, resolving the tension between the build_pdf name and the draft-creation behavior. It also distinguishes itself from a same-domain sibling by name (aiapplyd_optimize_resume), so an agent can route correctly 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-not ('Do not use it to rewrite a resume; use aiapplyd_optimize_resume'), a conditional gate for make_public ('only if the user explicitly asks to share'), a plan prerequisite (Hired in 30+), and the no-input branch behavior. Alternatives and selection conditions are stated outright 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?

Annotations already declare destructive/non-idempotent/not-readonly, and the description aligns with them by disclosing that a rewrite 'REPLACES the letter saved on the application' and that the output is saved to the account. It adds real value beyond annotations with credit consumption ('Generation and revision use the user's AI credits'), the plan not including cover letters, and resume fallback order, though auth/rate context is absent.

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

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

The core purpose is front-loaded, but the description is long and repeats itself – resume sourcing ('default saved resume-builder document... first saved builder document') is stated, then restated, and 'It also works without a resume-builder document' overlaps the fallback sentence. Tightening would remove 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?

For a five-parameter, zero-required, multi-mode tool with an output schema, the description covers every mode, the parameter combinations that select each mode, resume sourcing rules, plan gating, and credit behavior. Return values are covered by the output schema, so 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 description coverage is 100%, so the baseline is 3; the description goes beyond by explaining the resolution precedence for resume_text (pasted/attached text, else account base resume, else resume-builder document) and clarifying that application_id switches to read mode. It adds genuine precedence meaning the per-field schema text does not convey.

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

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

States a concrete verb+resource ('Write a cover letter for a specific job') and immediately distinguishes scope from the sibling, naming aiapplyd_apply as the tool for actually applying. Even the secondary read/revise modes are stated as actions, so an agent can classify the 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?

Covers when to write, when to read ('Pass application_id instead'), when to add instructions, and one explicit exclusion ('Do not use it to apply to a job; use aiapplyd_apply'). However the write/read/revise modes are interleaved in a way that makes selection less crisp than a 5, and no other resume siblings are positioned against it.

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

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

Beyond the annotations, the description discloses that a connected AI Applyd account is required, that the operation uses the user's AI credits, and that it saves the job to the account if not already saved. These are meaningful side effects and prerequisites that 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?

The description is compact and front-loaded with the deliverable, then covers usage, prerequisites, side effects, and exclusions. Every sentence earns its place, and the structure makes it easy for an agent to scan.

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 a complete input schema and an output schema present, the description covers the remaining operational essentials: account requirement, credit consumption, job-saving side effect, and the routing rule. An agent has enough to select and invoke 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 schema already documents each parameter. The description adds useful semantic context by explaining the mutually exclusive routing between application_id and the job_title/company_name pair, and clarifies that using application_id means no new saved job. This exceeds the baseline without adding much beyond the schema.

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

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

The description starts with an explicit verb and resource: 'Produce interview preparation for a specific role and company' and lists the concrete components it generates. It also distinguishes itself from aiapplyd_generate_cover_letter, making its purpose unmistakable.

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

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

It gives clear routing guidance: pass application_id for jobs the user applied to, or job_title and company_name otherwise. It also explicitly warns not to use it for cover letters and points to the correct sibling tool, which is strong when-to-use/alternative guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, but the description adds the credit-cost model ('it spends no credits'), which annotations cannot express. It also discloses readiness gating (resume on file, setup finished, missing profile fields), which is genuinely actionable behavioral context beyond the schema.

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

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

Front-loaded with the resource and its contents, then usage, exclusions and next steps in logical order. Slightly repetitive: 'changes nothing' and 'Do not use it to change anything' restate the same read-only guarantee, costing a few words.

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

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

An output schema exists, so the description does not need to explain return values, and the empty parameter set needs no documentation. What remains — when to call, what it protects (credits), and where to go next — is fully covered for a simple read-only tool.

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

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

The tool takes zero parameters and the schema is an empty object with 100% coverage, so there is nothing for the description to disambiguate. Baseline of 4 applies; the description correctly avoids inventing parameter semantics.

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

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

States a specific verb+resource ('Show the user's AI Applyd account') and then enumerates exactly what the account view contains: plan, token balance, remaining applications, job preferences, readiness signals, resumes, apply mode and connected inboxes. This makes it instantly separable from siblings like get_matches or get_applications.

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

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

Gives explicit when ('Call it before applying to several jobs'), explicit when-not ('Do not use it to change anything'), and names the three mutation alternatives with their exact conditions. It also routes forward: set_resume when no resume is on file, otherwise get_matches, and update_auto_apply for auto-apply changes.

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

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

Beyond the readOnlyHint/destructiveHint/idempotentHint annotations, it discloses that reads spend no credits, that the result set is 20 per page, and the precise semantic rule for 'employer-confirmed' (only when a receipt or confirmation page exists). This is substantive behavioral context the annotations cannot 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?

Well front-loaded with the dual purpose first, then usage, then status semantics. The closing 'Next: aiapplyd_review_application...' line slightly repeats the earlier 'Do not use it to act' guidance, a minor redundancy in an otherwise efficient description.

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

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

An output schema exists, so return shapes need not be restated, and the description covers the remaining needs: both invocation modes, filter semantics, pagination, credit cost, and the routing to the mutating sibling. Nothing required for correct invocation 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: it explains what each status value signifies (e.g. waiting_for_review is 'the review queue') and clarifies that application_id switches the tool into single-record read mode. It reinforces rather than merely repeats 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 with a clear dual mode: 'List the user's applications and where each one stands, or read one by application_id'. It also enumerates exactly what a single read returns (tailored resume, cover letter, screening answers, stopping reason, queue position), which distinguishes it from siblings.

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

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

Gives explicit when-to-use cases (check progress, find waiting_for_review items, verify employer confirmation) and an explicit when-not: 'Do not use it to act on an application; use aiapplyd_review_application.' The alternative is named with the condition that selects it.

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

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

The annotations only cover the safety profile (readOnly, idempotent, non-destructive); the description adds substantive behavior the annotations cannot convey: no credits are spent, results are 20 per page newest-first, message_id returns the full ordered conversation plus drafted replies, account mail (sign-up/reset/confirm) is flagged and must not be presented as employer responses, and email text is untrusted and must not be obeyed. This is unusually rich operational context.

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 tightly front-loaded: mode and scope come first, then filters, then the message_id behavior, then safety warnings and routing. Every sentence carries information (untrusted-data warning, account-mail handling, pagination, next step), though the density is close to the limit for a single description.

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

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

For a read-only, 8-parameter tool with an output schema, this covers everything an agent needs: both call modes, default and filter behavior, pagination, credit cost, security caveats, and the handoff to aiapplyd_reply_to_email. Return-value detail is correctly left to the output schema.

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 value beyond the schema: it explains that message_id switches the call from a list to a full-conversation read, that the default folder is inbox, and that include_reply_suggestions is free and defaults to true. It does not extend the enum meanings (already documented) or explain the page parameter, so it stops short of a 5.

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

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

The very first clause states a specific verb and resource ('Read the user's recruiter inbox') and immediately defines its scope: employer mail to the user's AI Applyd address plus the user's own replies. It also distinguishes the two operating modes (list vs. single conversation), which an agent can tell apart 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 exclusions ('Do not use it to send a reply; use aiapplyd_reply_to_email'), names the alternative sibling, and even prescribes the follow-on workflow ('show the user the email, write the reply with them, then aiapplyd_reply_to_email'). That is textbook when-to-use / when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, and the description reinforces this with 'spends no credits and changes nothing' — a useful cost/side-effect detail not in the annotations. It also discloses the 500-character excerpt limit and the newestJobMatchId checkpoint pattern for polling, adding real behavioral context beyond the structured hints.

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

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

Front-loaded with the primary purpose, then parameter behaviors, then usage boundaries and next steps — every clause carries operational information. It is a dense single paragraph that runs slightly long, but no sentence is redundant against the schema.

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

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

For a 9-parameter read tool with an output schema, it covers purpose, filtering modes, full-read escalation, incremental polling, cost profile, exclusions and next steps. Nothing an agent needs to invoke it correctly is missing, and return-value detail is already handled by the output schema.

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 meaning the schema does not: job_match_ids returns the full posting, skills and benefits (not just a list entry), job_url reads any posting without saving it, and after_job_match_id is tied to storing newestJobMatchId. These clarify intent rather than restating field types.

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

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

States a precise verb+resource ('List the user's matched jobs') and enumerates the returned fields (job_match_id, title, company, location, match score, 500-char excerpt, apply URL). It explicitly distinguishes itself from aiapplyd_update_job_preferences and routes onward to aiapplyd_apply and aiapplyd_triage_matches, so an agent can separate it from siblings without opening a schema.

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

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

Explicitly maps parameters to intents: job_match_ids to read full postings, job_url to read without saving, query/location/remote_only to narrow, after_job_match_id for incremental polling. It also gives a clear exclusion ('Do not use it to change what the user is matched against; use aiapplyd_update_job_preferences') and names next-step tools.

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

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

The annotations only flag destructive/openWorld/non-idempotent generically; the description concretizes them: send "cannot be undone", draft "spends tokens", send requires a connected Gmail or Outlook under the user's own name, and the exact approved text must be shown before sending. It also prescribes recovery behavior on timeout or error (call action history before retrying), which is behavior an agent cannot infer from annotations or schema.

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

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

The critical constraint (explicit user approval before send) is front-loaded after the action breakdown, and the safety-relevant sentences (irreversibility, mailbox dependency, retry rule) are all load-bearing. It is dense but not padded; the only mild redundancy is restating per-action parameter needs that the schema enum also lists.

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

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

An output schema exists, so return shape needn't be described. For an 8-parameter, multi-mode, destructive tool, the description covers consent, auth dependency, cost, failure recovery, ordering, and sibling routing — nothing an agent needs in order to call any action 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% and the action enum already documents per-action parameter needs, so the baseline is 3. The description still adds value by mapping actions to their side effects and ordering (list = most urgent first) and by tying parameters to workflow steps, though it largely mirrors the enum text rather than adding new syntax.

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+scope ("Follow up on applications that have gone quiet") and then decomposes the five action modes so the agent knows exactly what the tool does in each mode. It explicitly separates itself from the closest confusable sibling (aiapplyd_reply_to_email) rather than leaving that to inference.

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 ("Next: action draft for an application from the list"), a when-not-to-use exclusion ("Do not use it to answer an email an employer sent; use aiapplyd_reply_to_email"), a required consent protocol for send, and a fallback path when no mailbox is connected. That is routing, prerequisites, and alternatives in one place.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and non-idempotency, so the safety profile is covered. The description adds real context beyond that: 'delete removes one for good' flags irreversibility, and 'Nothing is sent to any employer and nothing is spent' bounds side effects. It does not describe alert delivery behavior or timing, keeping it just short of a 5.

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

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

A single dense paragraph that front-loads what the resource is, then walks the actions in order, then handles routing and safety. Every clause carries new information with no filler.

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

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

With an output schema present, return values need not be described, and the description covers action semantics, the prerequisite that saved_search_id comes from action list, and the destructive nature of delete. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so all four parameters (name, action, alerts_enabled, saved_search_id) are already documented in the schema, including the default naming behavior when save receives no name. The description restates the action semantics and which params apply to which action but adds no syntax or format detail beyond the schema. Baseline 3 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?

The description states a specific verb and resource ('Manage the user's saved searches: named snapshots of their job preferences') and enumerates each action's effect. It distinguishes itself from siblings by explicitly naming aiapplyd_update_job_preferences as the tool for changing match preferences and pointing to aiapplyd_get_matches as the next step.

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

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

It gives per-action when-to-use guidance ('action "list" shows them', 'call it only when the user asks' for delete) plus an explicit exclusion and the alternative to use instead ('Do not use it to change what the user is matched with; use aiapplyd_update_job_preferences'). 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 beyond the annotations by disclosing the account requirement and that the call consumes the user's AI credits, plus what the response contains. It does not clarify whether the rewritten resume replaces the resume stored on the account, which matters given readOnlyHint=false and idempotentHint=false.

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

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

Front-loaded with purpose and return payload, then routing rules, then prerequisites and the anti-sibling warning. Slightly redundant with the schema's own resume_file/resume_text descriptions, but every sentence carries usable instruction.

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 an output schema present it needn't explain return format, and it covers the three optional params and the account/credit prerequisites well. The remaining gap is whether the account resume is mutated or merely read, which is material for a non-read-only 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 100%, so the baseline is 3, but the description adds real routing semantics: job_description changes the optimization mode, resume_text accepts chat-pasted or attached text, and resume_file is the ChatGPT attachment path with the account fallback when omitted.

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

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

States a specific verb+resource ('Rewrite a resume so it passes ATS screening') and enumerates the return payload (rewritten resume, projected ATS score, itemised change summary). It explicitly distinguishes itself from the nearest sibling: 'Do not use it to apply: aiapplyd_apply tailors the resume for every application on its own.'

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 conditional routing: pass job_description to tailor to one posting, omit for general optimization; resume_text optional with fallback to the account resume; resume_file for ChatGPT attachments. It also states the exclusion against aiapplyd_apply and names prerequisites (connected AI Applyd account).

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

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

Annotations already declare destructive/non-idempotent/open-world, and the description reinforces this with 'real email... cannot be undone,' adds who it is sent as (user's name/address), a prompt-injection warning, and timeout/error retry behavior. This is rich behavioral context well beyond the structured fields.

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

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

Front-loads what the tool does and the irreversible nature, then layers the safety procedure and the follow-up step. It is longer than average but every sentence carries actionable information; no filler.

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

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

For a destructive, open-world write tool the description covers the safety profile, prerequisites, error handling, and next step, and an output schema exists so return values need not be restated. Complete for the agent's 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?

Schema coverage is 100%, so the baseline is 3, but the description adds sourcing context the schema lacks: message_id comes from aiapplyd_get_inbox and the reply targets the newest employer email, and body is the user-approved plain-text reply. Minor added value over the schema's own 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+resource ('Send the user's reply to an email from an employer') and immediately distinguishes itself from the read/draft siblings by naming aiapplyd_get_inbox as the tool not to use for those tasks. An agent can tell exactly what this does and what it does not.

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 ('only send on the user's explicit go-ahead'), a concrete procedure (show exact text, then send), when-not (don't use to read or draft), and an error-recovery path via aiapplyd_get_inbox. 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 annotations (destructiveHint, openWorldHint, idempotentHint=false) by naming which decisions are irreversible ('approve ... cannot be undone'), what reject does to the applicant ('nothing is sent'), and how a duplicate approve manifests ('an approve that already went through is reported as already approved'), which is exactly the idempotency nuance the annotation only flags abstractly.

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 destructive approve behavior and the per-decision effects before the constraints, so the highest-risk information lands first. It is dense and slightly run-on as a single block, with mild redundancy between the decision enumeration and the closing parameter restatement, but nearly every clause carries operational weight.

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

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

For a six-parameter, six-mode mutation tool with an output schema already present, the description covers the batch limit (up to 25 ids), the id source, error/timeout recovery, irreversibility, prerequisites, and the next step. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the final sentence adds a decision-to-parameter mapping the schema cannot express ('approve, reject and cancel need nothing else; refine needs document_type and instructions; set_stage needs stage; re_prepare takes optional steps'). It also states the batch cap and id provenance, though it does not explain refine instructions semantics beyond 'in the user's own words'.

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 ('Act on the user's applications') and then enumerates each of the six decision values with the concrete effect of each. It explicitly distinguishes itself from aiapplyd_apply and aiapplyd_triage_matches, so an agent can route without opening the schema.

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

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

Gives explicit when-to-use ('Only approve on the user's explicit go-ahead, such as a "yes" to a specific application'), when-not ('Do not use it for matches with no application yet'), named alternatives (aiapplyd_apply, aiapplyd_triage_matches), a retry protocol after timeout/error, and a follow-up tool.

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

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

Annotations only declare readOnlyHint=false, openWorldHint=false, idempotentHint=false, destructiveHint=false; the description supplies the non-obvious behavioral facts the agent actually needs — a connected AI Applyd account is required and the call consumes the user's credits. It does not state whether re-scoring is charged again or how failures are reported, so it stops short of a 5.

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

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

Front-loaded with purpose and return contents, then usage conditions, then parameter guidance — a sensible order. It loses a little efficiency by referencing aiapplyd_optimize_resume twice ('Do not use it to rewrite...' and 'Next: aiapplyd_optimize_resume rewrites...'), which is mild redundancy 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?

An output schema exists, so return values need not be explained, and the description still summarizes them. With account/credit prerequisites, the optional job_description mode, and the three resume input paths all covered for a zero-required-parameter tool, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the resume_text fallback ('Without it, the tool uses the resume already on the user's account') and the ChatGPT attach path for resume_file. The interaction between resume_text, resume_file and the stored account resume is the key semantic the schema alone cannot convey.

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

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

States a specific verb and resource ('Score a resume for ATS compatibility') and immediately enumerates the return contents (overall score, section scores, matched/missing keywords, rewrite suggestions). It also explicitly distinguishes itself from the sibling aiapplyd_optimize_resume, so an agent can route correctly without opening either schema.

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

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

Gives explicit conditional usage: 'Pass job_description to score against a posting, or omit it for a general ATS readiness score.' It names the when-not case ('Do not use it to rewrite the resume; use aiapplyd_optimize_resume') and even suggests the next step, leaving no routing ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds the deprecation status—a behavioral trait not captured in structured fields—plus the domain-specific guarantee that it never changes which roles are hunted. It could say more about response/pagination behavior, but with annotations carrying the safety profile this is solid.

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

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

Three sentences, front-loaded with the deprecation warning so the most important routing fact is read first. The middle sentence partially restates the schema, but there is little wasted space overall.

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 an output schema present and full parameter coverage, the description need not explain return values; it covers deprecation, behavior and equivalence. Complete enough for a deprecated alias, though it stops short of noting whether the alias will be removed or how strictly it mirrors get_matches output.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, making 3 the baseline. The description adds a mapping ('title, location and remote' correspond to get_matches' 'query, location and remote_only'), which is mildly useful for equivalence but does not add syntax or format detail.

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

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

The description states a specific resource ('the user's matched jobs') and its filtering dimensions (title, location, remote), and explicitly identifies itself as a deprecated alias of aiapplyd_get_matches. An agent can distinguish it from that 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?

It gives direct, explicit routing: 'Deprecated alias of aiapplyd_get_matches, use aiapplyd_get_matches.' The condition under which the alternative should be used is stated unambiguously, so there is nothing left to infer.

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

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

Annotations already flag destructive=true and non-idempotent, and the description corroborates rather than contradicts: it warns the call replaces the current base resume while the old one stays in documents, notes that a new upload consumes AI credits whereas document_id is free, and discloses the side effect of finishing account setup and starting job discovery. That is a rich behavioral disclosure beyond the annotation flags.

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 the structure is front-loaded: purpose, then the exactly-one rule, then costs, then usage, then next step. A couple of sentences (the resume_file attachment note) largely restate the schema, which is the only waste.

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, four-parameter tool with a nested object and an output schema, the description covers the selection rule, cost trade-offs, prerequisite lookup, replacement semantics, and follow-up tool. Nothing needed to call it correctly is missing, and return values are correctly left to the output schema.

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, but the description adds real meaning: it states the mutual-exclusivity rule ('Pass exactly one') that the schema does not enforce via oneOf/anyOf, plus per-option cost implications and the ChatGPT file-attachment path. Minor gap: the 10 MB / 50k-char limits are already in the schema and are simply repeated.

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 ('Put the user's resume on their AI Applyd account as the base every application is tailored from') and explicitly distinguishes itself from aiapplyd_optimize_resume and aiapplyd_score_resume. An agent can tell it apart from siblings 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 an explicit trigger ('when aiapplyd_get_account shows no resume on file, or when the user gives a new one'), an explicit exclusion ('Do not use it to rewrite or score a resume'), named alternatives, and a next step (aiapplyd_get_matches). This is textbook when/when-not/alternatives guidance.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false; the description adds real context beyond them: the translation is saved as a separate resume with the original unchanged, it consumes AI credits, and the attached file is downloaded once immediately (10 MB, PDF/DOCX/text). It does not mention rate limits or how credits are consumed, so it stops short of full disclosure.

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

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

The purpose and prohibition are well front-loaded, but the source-resolution logic is restated three times across the paragraph ('Works from the user's resume on file, or a resume they paste or attach...' / 'It also works without a resume-builder document...' / 'It uses the resume the user pasted or attached...'), and language examples are duplicated. It meanders where two tight sentences would do.

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

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

An output schema exists, so the return values need not be explained, yet the description still covers them briefly. Across a 1-required-param tool with a nested resume_file object, it covers sources, language, credits, non-destructiveness, and alternatives — only the credit-consumption mechanics are left open.

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. The description nonetheless adds routing semantics the schema cannot: pass pasted/attached conversation text as resume_text, pass a ChatGPT attachment as resume_file, and omit resume_text to fall back to the account resume. That precedence logic is genuinely useful beyond the field 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 (translate) and resource (resume), plus the exact scope of which document is translated (the default saved resume-builder document, or the first saved one if no default). It also names the sibling tools it is not (aiapplyd_optimize_resume, aiapplyd_apply) with the reason, so an agent can distinguish it without opening another schema.

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

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

Explicitly says when not to use it ('Do not use it to tailor a resume to a job; use aiapplyd_optimize_resume, or aiapplyd_apply') and enumerates the source-resolution order (pasted/attached text, then account base resume, then resume-builder document). The alternative is named with the selecting condition, leaving little to inference.

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

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

Adds real behavior beyond annotations: skip reasons feed the matcher to improve future matches, and 'Nothing is sent to any employer and nothing is spent' addresses side-effect concerns that the idempotent/destructive hints don't cover. Doesn't note whether saved items can later be un-saved, but the persistence and feedback-loop semantics are well disclosed.

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

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

Front-loaded with the core action, then constraints, side-effect guarantees, an exclusion, and a next step. The long reason list is dense but justified since it's the enum values. Slightly dense but every clause carries routing or behavior 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?

Given an output schema exists, return values needn't be explained. The description covers the action semantics, side effects, source of ids, exclusions, and follow-up. For a 3-param mutation tool this is essentially complete; only a note on un-saving saved matches 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. The description adds meaning: reason enum values are enumerated in prose and tied to the skip action, and job_match_ids is bounded at 25 and sourced from aiapplyd_get_matches in a way that exceeds the schema's bare description.

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

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

States a specific verb pair (save/skip) on a specific resource (job matches) and frames the trigger question 'want this one?'. It distinguishes itself from siblings by naming aiapplyd_get_matches as the source and aiapplyd_apply as the different action.

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 exclusions: 'Do not use it to apply; use aiapplyd_apply.' Explicit source: 'Pass up to 25 job_match_ids from aiapplyd_get_matches.' Explicit next step: 'Next: aiapplyd_get_matches for the next matches.' When-to-use and the alternative are both provided.

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 and readOnlyHint=false; the description explains the mechanism behind that (only passed fields change, null clears one) and adds context annotations cannot carry: the policy to save only user-given answers and never guesses, and the explicit side-effect statement that nothing is sent to any employer and nothing is spent. It also flags the EEO fields as optional and sensitive with a decline path.

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

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

Front-loaded with purpose, then read mode, write mode, safety policy, exclusions, and next steps in a logical order with no filler. It is somewhat long, but for a tool covering 33 fields with read/write dual behavior and sensitive data, nearly every sentence carries load.

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

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

An output schema exists, so return formatting need not be explained, and the description still covers the read-mode payload conceptually ('open questions: required fields that are empty, and details recent applications had to guess'). With zero required parameters, the patch-style semantics, the clearing behavior, and the provenance policy are all disclosed, leaving nothing an agent needs in order to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, and each field description already states its own meaning and sensitivity. The description adds meaning the schema does not: that a null value clears a field (only implied by the anyOf null schema), that personal_narrative feeds interview preparation, and how the declared fields group into employer-form answers. It does not add per-field syntax beyond that.

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

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

States a specific verb and resource ('read or update the user's application profile'), names the concrete content domain (contact details, work authorization, declarations, EEO answers), and explicitly distinguishes itself from aiapplyd_update_job_preferences. An agent can identify and separate this tool from its ~20 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?

Gives explicit invocation modes ('call it with no fields to read', 'pass fields to save them'), an exclusion with a named alternative (job preferences → aiapplyd_update_job_preferences), and a next-step route (aiapplyd_get_matches / aiapplyd_apply). This is exactly the when/when-not/alternatives structure needed for a 33-parameter tool.

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

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

Annotations declare non-readonly, destructive, idempotent, open-world, but the description adds substantial context they cannot convey: the Hired Yesterday plan prerequisite, that a failed plan check changes nothing, that "auto" mode sends immediately and cannot be undone, and that the returned payload is the settings. This goes well beyond the annotations.

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

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

Front-loaded with the core action, then behavior, then guardrails and routing. It is dense and long, but nearly every sentence carries distinct information; a small trim of the redundant mode explanation would be possible 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?

An output schema exists, so return values need not be described; the description still notes that it returns the settings. All four optional parameters, their omission semantics, the plan gate, and the sibling routing are covered, leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is 100% and enums are self-documented, so the baseline is 3. The description adds genuine cross-parameter meaning by explaining that default_apply_mode is also the mode aiapplyd_apply falls back to when omitted, which the schema does not state.

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 (change/update) and resource (Auto Apply settings), then enumerates exactly which settings (enabled, apply mode, daily limit, match level). It clearly distinguishes itself from aiapplyd_apply and aiapplyd_auto_apply by naming 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?

Explicit trigger (only when the user asks to change these settings), explicit exclusion (never on your own), names the alternative tool for the adjacent task (aiapplyd_apply for a single application), and states a next step (aiapplyd_get_applications). Nothing is left to inference.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the write/replace risk is signposted. The description adds non-obvious behavior the annotations cannot convey: lists REPLACE rather than append (data loss on partial input), discovery is re-run immediately, the free-text `description` consumes AI credits, and fields win over prose. This is exactly the added value a description should provide on top of structured fields.

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

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

Front-loaded with purpose and the replace/credits caveats before the parameter enumeration, and every clause carries operational meaning. The long parenthetical field list and the application_answers sentence make it denser than necessary, but nothing is pure filler.

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

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

For a 15-parameter, nested-object, currently-mutating tool with an output schema, the description covers the prerequisites, the destructive replace behavior, the free-text precedence rule, the credits cost, and the correct sibling for searching. An agent has everything needed to call it safely.

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 meaningfully exceeds it: it explains the precedence rule between the free-text `description` and explicit fields, the destructive replace semantics for list params, and the correct usage for the nested `application_answers` object (fill only user-stated values, never guesses). It does not add guidance for the deprecated `remote_only` vs `include_remote` migration beyond what the schema already carries.

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

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

States a specific verb (Update/Set) and resource (job preferences: target roles, locations, remote, salary band, seniority, work styles, job types, visa sponsorship, exclusions, pause) and explicitly names what it is not (a search tool). An agent can distinguish it from aiapplyd_get_matches, aiapplyd_search_jobs, and aiapplyd_update_application_profile 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?

Explicit trigger ("Only call this when the user asks"), an explicit prerequisite ("Read the current preferences first with aiapplyd_get_account"), and an explicit exclusion with the alternative to use instead ("Do not use it to search; use aiapplyd_get_matches with query"). This is the full when/when-not/alternative pattern.

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