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

Beyond the annotations, the description discloses meaningful operational context: it requires a connected AI Applyd account and consumes the user's AI credits. It does not contradict the annotations, and while it doesn't detail all side effects, the added auth and cost information is useful.

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 four sentences with no filler. The primary purpose is front-loaded, followed by usage timing, an exclusion with the correct alternative, and next-step recommendations—all in a compact, scannable structure.

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

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

For a single-parameter analysis tool with an output schema and annotations, the description covers purpose, when to use, when not to use, alternatives, required account state, and cost implications. Nothing essential 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 description coverage is 100%, and the only parameter, job_description, is already documented as 'Full text of the job description' in the schema. The tool description doesn't add much parameter-specific meaning beyond that, which matches the baseline for high schema coverage.

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: 'Extract what a job posting actually screens on,' and enumerates concrete outputs (ATS keywords, must-have versus nice-to-have requirements, seniority signals, red flags). This clearly distinguishes it from sibling tools like aiapplyd_get_matches and aiapplyd_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?

It explicitly says when to call it ('Call this before tailoring a resume'), what not to use it for ('Do not use it to read a posting from a link'), and names the alternative (aiapplyd_get_matches with job_url). It also chains the next steps by recommending aiapplyd_score_resume or aiapplyd_optimize_resume afterward.

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 goes beyond the annotations by detailing that it rewrites the resume and cover letter, submits on the employer's system, spends applications and AI credits, and that a submitted application cannot be withdrawn. It also flags idempotency behavior (alreadyExisted) and error handling guidance, all of which are not in the annotations. This fully discloses the destructive, non-idempotent nature in concrete terms.

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 each sentence earns its place; it is front-loaded with the core purpose and then methodically covers identifiers, behavior, side effects, error handling, and alternatives. While it could be tightened, the density is justified for a destructive, high-stakes operation.

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 the complexity of the operation (external submission, side effects, error handling), the description covers all necessary aspects: how to identify the job, what the tool does, side effects, retry guidance, and follow-up tools. The existence of an output schema means return values don't need to be spelled out, and the description is complete for an agent to invoke 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. The description adds value by explaining that job_match_id must come from aiapplyd_get_matches and that job_url works for any posting, plus clarifying that mode applies only to this application and never changes user settings. These semantics go beyond the schema's field-level descriptions without being redundant.

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 'Apply to one job on the user's behalf,' which states a specific verb and resource. It further distinguishes itself by explaining how to identify the job (via job_match_id from aiapplyd_get_matches or job_url) and explicitly says not to use it for saving or skipping matches, directing to aiapplyd_triage_matches. This makes it clear among the 16 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?

It provides explicit when-to-use guidance: 'apply only to jobs the user chose' and gives exact alternatives for other actions: 'Do not use it to save or skip a match; use aiapplyd_triage_matches.' It also maps next steps (aiapplyd_get_applications, aiapplyd_review_application) and clarifies the mode semantics, leaving no ambiguity about when to invoke this tool versus other 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 already establish that this is destructive and not read-only; the description adds meaningful context by stating it 'spends one of the user's applications' and by scoping the action to one job posting across listed ATS systems. It does not cover auth or rate limits, but the key consequence is disclosed.

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

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

The deprecation warning is front-loaded, and every subsequent clause carries operational meaning: one job, end-to-end, supported systems, review setting, and cost. The ATS list is long but directly tells an agent where the tool works, so no sentence is wasted.

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

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

For a one-parameter tool with an output schema and rich annotations, this description covers the essential operational facts: what is acted on, the supported contexts, the review behavior, and the irreversible cost. Nothing needed to decide whether to invoke 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% and the single job_url parameter is already documented as 'URL of the job posting to apply to.' The description reinforces that the URL selects a single job, but it adds no format, normalization, or other parameter-level detail 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 states a concrete action ('applies to ONE job posting by job_url, end to end') and identifies the target resource, and it explicitly distinguishes itself from aiapplyd_apply by declaring itself a deprecated alias. This leaves no ambiguity about what the tool does or which sibling should be used.

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 opens with an explicit directive: 'Deprecated alias of aiapplyd_apply, use aiapplyd_apply.' It also specifies when the underlying behavior applies (one job URL, on the employer's own ATS, following the review setting), so an agent knows both the alternative and the conditions around use.

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 state readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds valuable behavioral details: the result stays editable and downloads as a PDF, defaults to private, requires a paid plan, and consumes AI credits. It doesn't contradict annotations. Could perhaps mention side effects more deeply, but the description adds solid 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?

Four sentences, each earning its place: what it does, templates, privacy default, paid plan/credits, and forked routing to sibling. Front-loaded with the main verb and artifact. No fluff.

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 the output schema exists (so return values are documented), the parameters are fully covered in the schema, and the description covers usage, privacy, and exclusions, nothing an agent needs to invoke correctly is missing. It even flags account requirements and alternative tool routing.

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 thoroughly documents all 3 parameters, including the make_public privacy warning. The description adds the privacy default context but doesn't add much beyond the schema for parameters. Baseline 3 is appropriate since the schema carries the load.

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 clearly states the specific verb (build), resource (resume in AI Applyd), and key output (ATS-clean PDF, editable). It also distinguishes from siblings by explicitly saying 'Do not use it to rewrite a resume; use aiapplyd_optimize_resume.' The scope is unambiguous.

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

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

The description explicitly says when to use (build a formatted resume from raw text) and when not to (not for rewriting; use aiapplyd_optimize_resume instead). It also gives context on privacy and paid plan requirements, which helps an agent decide if it's the right 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?

Beyond the minimal annotations (readOnlyHint false, etc.), the description discloses that the tool saves the letter to the account, uses AI credits, requires a resume and paid plan, and gracefully handles missing prerequisites by informing the user. It also reveals the two operational modes and the stylistic behavior of avoiding recruiter cliches. No contradictions with 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 information-dense yet efficient, front-loading the core purpose and then covering prerequisites, alternative usage, and exclusions. Every sentence contributes necessary detail without redundancy. The structure flows logically from action to caveats to alternative.

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 the tool's complexity (two modes, prerequisites, credit usage) and the presence of an output schema, the description covers all essential aspects: the two modes, what happens when prerequisites are missing, the credit usage, and the alternative tool. Nothing critical is omitted for an agent 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 baseline is 3. The description adds value by explaining the relationship between parameters: company_name and job_description are used together, while application_id is an alternative, and instructions only apply when application_id is provided. This relational context is not in the schema and helps correct usage.

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 clearly states the tool writes a cover letter from the user's base resume for a specific job, and explicitly distinguishes it from aiapplyd_apply by warning not to use it for applications. The verb 'write' and resource 'cover letter' are specific, and the alternative mode via application_id is clearly explained.

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

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

The description gives explicit when-to-use guidance: use for writing a new cover letter, or pass application_id to retrieve an existing one. It also states exclusions (aiapplyd_apply already writes cover letters for applications) and prerequisites (resume on file and paid plan), including what happens if they're missing. This leaves no ambiguity about when to choose this tool.

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

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

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 mark readOnlyHint and destructiveHint false, but the description adds valuable detail not in annotations: 'it spends no credits and changes nothing.' This clarifies the credit cost, a side effect an agent must know. No contradiction with 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?

The description is information-dense but tightly organized: it opens with the tool's primary output, then gives usage timing, then read-only behavior, exclusions, and follow-up steps. Every sentence adds necessary guidance without padding or repetition.

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

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

Given the tool takes no inputs and has an output schema, the description fully covers the operation: what it shows, when to call it, what not to use it for, and what to do next. Nothing an agent needs 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?

The tool has zero parameters and the schema is fully documented (vacuously, 100% coverage). With 0 params, the baseline is 4; the description does not need to discuss parameters since there are none.

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

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

The description explicitly states the tool shows the user's AI Applyd account with a detailed breakdown across plan, tokens, applications, preferences, readiness, resumes, and apply mode. It also distinguishes itself from sibling tools by explicitly naming the change tools it is not: 'Do not use it to change anything; use aiapplyd_update_job_preferences or aiapplyd_set_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?

Provides explicit when-to-use guidance: 'Call it first, and before applying to several jobs.' It also gives explicit alternatives and when-not: 'Do not use it to change anything; use aiapplyd_update_job_preferences or aiapplyd_set_resume.' Next-step logic is even provided based on resume status.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description reinforces this by stating 'Read-only: it spends no credits.' It adds valuable behavioral context beyond the annotations: pagination details ('Returns 20 per page'), the strict definition of 'employer-confirmed', and what content is included for a single application. This fully discloses the tool's behavior 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?

The description is information-dense but well organized: it leads with the core purpose, then use cases, confirmations, statuses, pagination, and a clear pointer to the sibling tool. There is slight redundancy where the 'Do not use it... use aiapplyd_review_application' instruction is repeated in the closing sentence, but overall every sentence earns its place.

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

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

For a tool with three parameters, rich annotations, and an output schema, the description is complete: it explains read behavior, credit implications, pagination, status meanings, and the exact distinction from aiapplyd_review_application. Nothing essential is missing for an agent to select and invoke this tool correctly.

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

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

Input schema coverage is 100%, with all three parameters already described. The description adds meaningful context by explaining the status filter semantics, the pagination behavior tied to the page parameter, and that application_id reads one application in detail. It does not fully define every status value, but it compensates well beyond the baseline for schema-covered parameters.

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 precise verb and resource: 'List the user's applications and where each one stands, or read one by application_id.' It also specifies what is returned for a single application, including the tailored resume, cover letter, screening answers, queue status, and employer confirmation image. It clearly distinguishes itself from the sibling action tool by stating it is not for acting on 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?

The description explicitly tells the agent when to use this tool: 'Use this to check progress, to find applications waiting for the user's approval... or to see whether an employer confirmed a submission.' It also provides an explicit exclusion: 'Do not use it to act on an application; use aiapplyd_review_application.' This is exemplary when-to-use versus 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?

Even with annotations declaring readOnlyHint, idempotentHint, and destructiveHint, the description adds valuable behavior details: 'Read-only: it spends no credits and changes nothing'. It also clarifies semantics like reading a posting via job_url 'without saving it' and using after_job_match_id with stored newestJobMatchId for incremental checks.

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

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

The description is dense but well-structured: core purpose first, then filtering/reading modes, then read-only guarantee, then guardrail and next-step suggestions. Every sentence contributes behavioral or routing information, and the key constraints are front-loaded.

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 the 9 optional parameters, rich input schema descriptions, output schema, and annotations, the description covers all essential usage modes, read-only behavior, credit implications, and next-step routing. Nothing an agent needs to select and invoke this tool correctly is missing.

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

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

The input schema already fully describes all 9 parameters, so the baseline is 3. The description adds useful context beyond the schema, such as job_match_ids being limited to 10 and returning 'the full posting, skills and benefits', and explaining the after_job_match_id pattern with newestJobMatchId. This justifies above baseline, though much of the added value repeats or summarizes 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?

The description opens with a specific verb and resource: 'List the user's matched jobs'. It further specifies that these are roles found against saved preferences, sorted best-first, and mentions key fields returned. This clearly distinguishes it from sibling tools like aiapplyd_search_jobs or aiapplyd_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?

The description explicitly states 'Do not use it to change what the user is matched against; use aiapplyd_update_job_preferences for that', giving a direct exclusion and alternative. It also routes the next step: pass a job_match_id to aiapplyd_apply or save/skip with aiapplyd_triage_matches. No ambiguity remains about when to use this tool.

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

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

The description adds meaningful behavioral context beyond annotations: it discloses that the tool uses the user's AI credits and requires a connected account. It also states that it returns a rewritten resume and a summary, implying it does not modify the stored resume directly. The annotations already indicate it is not read-only and not idempotent, so the description complements them with concrete side effects (credit usage) and prerequisites. It could go further by clarifying whether the rewrite is saved or only returned, but the current level is strong.

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: it opens with the primary purpose and outputs, then covers optional usage, prerequisites, and an explicit sibling differentiation. Every sentence serves a purpose with no redundancy. It is well-structured and easy to parse.

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 the tool's complexity (mutation, credit consumption, optional tailoring), the description covers all essential aspects: what it does, what it returns, when to use the optional parameter, prerequisites, and when not to use it. The output schema exists, so return values are partially documented, but the description still summarizes them clearly. No critical information is missing for an agent to 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?

The input schema already describes both parameters fully (100% coverage), so the baseline is 3. The description adds value by explaining the purpose of job_description ('to tailor the rewrite to one specific posting') and the omit condition ('general ATS optimization'), which is not explicit in the schema. It also implies that resume_text is the full text to be optimized, aligning with the schema. This goes beyond a simple restatement of parameter 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?

The description states a clear verb+resource: 'rewrite a resume so it passes ATS screening.' It also lists the exact outputs (rewritten resume, ATS score, itemised summary) and distinguishes itself from the sibling aiapplyd_apply by explicitly warning not to use it for applying. This makes the tool's purpose unambiguous and sets it apart from other resume-related 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?

It gives explicit usage guidance: pass job_description to tailor to one posting, or omit for general optimization. It also names aiapplyd_apply as the alternative for applying and states 'Do not use it to apply', leaving no ambiguity about when to choose this tool over a sibling. Additionally, it mentions prerequisites (connected AI Applyd account) and credit consumption, which are relevant usage constraints.

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 provide destructiveHint=true and idempotentHint=false, and the description richly elaborates on those: 'approve' 'spends one of their applications per job and cannot be undone', 'reject' sends and spends nothing, 'refine' 'uses AI credits', and a retried approve that already went through 'is reported as already approved'. This adds meaningful behavioral context beyond the annotations without contradicting 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 every sentence earns its place. It front-loads the core action and decision inventory, then layers constraints (id source and cap, consent rule, timeout recovery), exclusions, and the follow-up call. For a six-mode tool with error handling and sibling routing, this density is appropriate with zero fluff.

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 no prose explanation. The description covers everything needed for safe invocation: all six behaviors, the decision-to-parameter coupling, id sourcing and limits, the explicit-go-ahead consent rule, timeout/error handling, when-not-to-use with named alternatives, and the next step ('aiapplyd_get_applications to follow the submissions'). Nothing an agent needs 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: it couples decisions to their required parameters ('refine' needs document_type and instructions, 'set_stage' needs stage, 're_prepare' takes optional steps), caps application_ids at 25, and specifies that ids come from aiapplyd_get_applications. This explains the interplay between parameters that the schema's per-field descriptions do not.

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

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

The description opens with a clear verb and resource ('Act on the user's applications') and then enumerates each decision mode ('approve', 'reject', 'cancel', 'refine', 're_prepare', 'set_stage') with its specific effect. It also distinguishes itself from siblings by naming aiapplyd_apply and aiapplyd_triage_matches as the tools for matches with no application yet.

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

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

Provides explicit when-to-use guidance: pass up to 25 ids 'from aiapplyd_get_applications' and only approve 'on the user's explicit go-ahead'. Explicitly states when not to use it ('Do not use it for matches with no application yet; use aiapplyd_apply or aiapplyd_triage_matches') and gives recovery guidance for timeouts and errors. This is full when/when-not/alternatives coverage.

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

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

With annotations indicating readOnlyHint=false, destructiveHint=false, and idempotentHint=false, the description adds critical context: it requires a connected AI Applyd account and uses the user's credits, implying a cost. It also discloses the action is non-idempotent (credits spent) and not destructive. This goes beyond the annotations by explaining the account requirement and credit consumption.

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 efficient, with each sentence serving a purpose: defining outputs, explaining usage options, noting prerequisites, and routing to the sibling. It front-loads the core purpose and then the usage, and the sibling routing is placed at the end, helpful for flow.

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 the tool's moderate complexity, the output schema exists to document return values, and parameters are fully covered in schema, the description is complete: it states the inputs, the optionality, the account requirement, credit usage, and the boundary with the optimization tool. Nothing essential is missing for an agent 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 both parameters (resume_text and job_description) are documented in the schema. The description adds the distinction between omitting job_description for a general score, which aligns with the schema's optional note. However, it doesn't add syntax or format details beyond that, so 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 clearly states the tool scores a resume for ATS compatibility, lists the specific outputs (overall score, section scores, keywords, suggestions), and differentiates it from the sibling aiapplyd_optimize_resume by explicitly stating it does not rewrite. The verb 'Score' and resource 'resume' are specific, and the mention of optional job_description clarifies variants.

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

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

The description provides clear guidance on when to use it: pass job_description to score against a posting, or omit for general ATS readiness. It explicitly states 'Do not use it to rewrite the resume; use aiapplyd_optimize_resume' and names the alternative. This directly addresses selection among siblings and gives a next-step recommendation.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which covers safety. The description adds the explicit read-only guarantee ('it never changes which roles AI Applyd hunts for') and deprecation status, which goes beyond the annotations by explaining the operational impact of the alias.

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 two sentences long, with the deprecation warning and redirection front-loaded, and no filler. Every clause adds relevant information about the alias, behavior, and read-only safety.

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 the output schema exists, annotations cover safety and idempotency, and the description covers alias behavior and parameter mapping, nothing essential is missing. The agent has full information to decide whether to call this tool or its replacement.

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 parameters are fully documented. The description adds value by mapping each filter to the original tool's parameters (query, location, remote_only), clarifying the alias relationship for the agent, which is especially helpful given the deprecated status.

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

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

The description clearly states it returns matched jobs filtered by title, location, and remote, and immediately identifies itself as a deprecated alias of aiapplyd_get_matches, distinguishing it from siblings. The verb 'returns' combined with the filter criteria makes the purpose specific and unambiguous.

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

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

Explicitly instructs the agent to use aiapplyd_get_matches instead ('use aiapplyd_get_matches'), and clarifies the exact parameter mapping (query, location, remote_only), providing both a when-not-to-use directive and a direct alternative.

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

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

Annotations only indicate non-read-only, non-idempotent, and non-destructive behavior. The description adds meaningful behavioral context: a new upload consumes the user's AI credits, switching to a saved resume with document_id is free, and setting the resume also completes account setup and triggers job finding. This is valuable side-effect information beyond what the annotations provide.

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

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

The description is relatively long, but every sentence earns its place: purpose, parameter selection, side effects, use conditions, exclusions, and next step. It is front-loaded with the core purpose and structured logically, so an agent can quickly extract the essential behavior without wading through 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?

Given the tool's complexity and the presence of annotations and an output schema, the description covers everything an agent needs: what the tool does, how to choose a parameter, credit cost, account setup implications, when to use it, when not to use it, and the recommended next tool. There are no meaningful gaps.

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

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

Schema coverage is 100%, but the description still adds semantic value by clarifying that exactly one of the three parameters must be passed and by explaining the cost implication: uploading a new resume uses AI credits, while using document_id is free. This is genuinely useful guidance beyond the schema's 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?

The description uses a specific verb and resource: it puts the user's resume on their AI Applyd account as the base for tailoring applications. It also distinguishes itself from sibling tools by explicitly saying it should not be used to rewrite or score a resume, naming aiapplyd_optimize_resume and aiapplyd_score_resume as the correct alternatives.

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

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

The description gives explicit conditions for use: when aiapplyd_get_account shows no resume on file, or when the user provides a new resume. It also states what not to use it for and directs the agent to specific sibling tools, making the selection decision unambiguous.

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

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

Beyond the annotations, the description explains important side effects and safety-related behavior: the translation is saved as a separate resume, the original stays unchanged, and the operation uses AI credits. It also states what the return value contains (new resume title and link), adding meaningful behavioral context beyond the raw 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 informative yet compact, front-loading the core purpose before adding return information, prerequisites, and exclusions. Every sentence earns its place, with no redundant or filler content.

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

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

For a single-parameter tool with an output schema and annotations, the description covers the key operational context: prerequisite resume, credit usage, side effects, return value, and when to use a different tool. Nothing essential is missing for an agent to decide whether and how to invoke this tool correctly.

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

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

Schema coverage is 100% and the single parameter target_language is already documented in the schema, so the baseline is 3. The description reinforces the parameter by giving example languages, but does not add substantial new semantics beyond what the schema already provides.

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

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

The description names the specific operation (translate the user's saved base resume) and the resource, and clearly distinguishes it from related tools like aiapplyd_optimize_resume and aiapplyd_apply. The purpose is unambiguous, and even the context of where the translation can be sent is included.

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

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

The description explicitly states when to use this tool (translating an existing resume for another market) and when not to use it (tailoring a resume to a job), naming the alternatives aiapplyd_optimize_resume and aiapplyd_apply. It also notes the prerequisite of having a resume on file and that the operation consumes AI credits, giving an agent clear selection criteria.

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 adds important behavioral details: skipping makes matches stop showing, saving adds them to the user's saved list, the reason teaches the matcher, and nothing is sent to any employer or costs anything. This gives the agent a clear model of real-world side effects 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?

The description is compact and front-loaded: it leads with the core action, explains the parameters inline, and then covers safety, exclusions, and next steps. Every sentence earns its place with no filler or repetition.

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

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

For a tool with three parameters, two enums, and an output schema, the description is complete enough to guide correct invocation. It covers what the tool does, what inputs to pass, the optional reason, the no-external-effect guarantee, the explicit non-application use case, and the natural next step.

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

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

The schema already covers all parameters with 100% coverage, but the description adds meaningful context by explaining that 'skip' dismisses matches so they stop showing, the reason 'teaches the matcher,' and that job_match_ids come from aiapplyd_get_matches with a max of 25. This is more than a restatement of the schema.

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

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

The description states a specific verb and resource: 'Save or skip job matches' and explains the two actions 'save' and 'skip' in concrete terms. It also explicitly distinguishes itself from aiapplyd_apply, so an agent can tell this tool apart from the most similar sibling.

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

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

The description gives clear usage context: use this to save or skip matches, pass up to 25 IDs from aiapplyd_get_matches, and optionally provide a skip reason to teach the matcher. It explicitly says 'Do not use it to apply; use aiapplyd_apply' and points to aiapplyd_get_matches as the next step.

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 valuable side-effect context beyond annotations: 'Lists REPLACE what is saved, so pass the complete list, not an addition,' 're-run discovery immediately,' and 'fill only values the user stated, never guesses.' These details enrich the destructiveHint and idempotentHint annotations without contradicting 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?

Every sentence earns its place: purpose, immediate side effects, replacement semantics, application_answers caution, call condition, prerequisite, and sibling routing. The most critical behavioral caveats are front-loaded before secondary details.

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

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

For a 15-parameter, nested-object mutation tool with full schema coverage and an output schema, the description covers call conditions, destructive replacement behavior, natural-language precedence, the application_answers safety rule, and exclusion of search usage. Nothing an agent needs 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% and parameter descriptions already include key rules like 'REPLACES the saved list' and 'Fields passed explicitly win over it.' The main description adds useful aggregate guidance ('pass the complete list, not an addition') and the read-before-update prerequisite, but only modestly exceeds 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?

Description opens with a specific verb and resource ('Set what AI Applyd hunts for on the user's behalf') and enumerates the preference dimensions it updates. It also explicitly differentiates from siblings by saying 'Do not use it to search; use aiapplyd_get_matches with query.'

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 conditions: 'Only call this when the user asks,' a prerequisite ('Read the current preferences first with aiapplyd_get_account'), and a clear exclusion for search usage with the alternative tool named. This is strong 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.