GetMattered (moved)

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

Against annotations of readOnlyHint=false and idempotentHint=false, the description clarifies that no resume or settings are modified and that the only real cost is AI credits from a connected account. It doesn't address whether repeated calls consume credits again (relevant given idempotentHint=false), leaving a small gap.

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: purpose first, then behavioral constraints, then the exclusion, then the follow-up chain. Every clause carries differentiating information and there is no repetition of the title or 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?

An output schema exists, and the description still summarizes the return shape (category, importance, must-have). Combined with the account/credit prerequisites and next-step guidance, 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?

With a single parameter at 100% schema coverage, the schema already defines job_description. The description adds useful semantics by implying the input is the full posting text rather than a link, which shapes the value an agent supplies.

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 ('Extract') and names the exact resource and output shape (ATS keywords and requirements with category, importance, must-have flag). It also distinguishes itself from getmattered_get_matches, which handles link-based reading.

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 an explicit when-not ('Do not use it to read a posting from a link; use getmattered_get_matches with job_url') and concrete next-step routing to score_resume or optimize_resume with the same job description. There's no ambiguity about when this tool is the right choice.

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

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

Goes well past annotations by disclosing cost (one application plus AI credits), irreversibility ("a submitted application cannot be withdrawn"), idempotency behavior (returns the existing application with alreadyExisted true rather than duplicating), error-recovery protocol (call getmattered_get_applications before retrying; never re-apply by job_url), and the free-tier limit of five applications.

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?

Cost, irreversibility, and the outcome/error handling are front-loaded and every sentence carries operational information. The main drag is the exhaustive 30-name enumeration of hiring systems, which conveys open-world scope but could be summarized; the description is long yet dense rather than padded.

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?

This is a destructive, open-world, non-idempotent write with an output schema. The description covers what gets submitted, what happens on unsupported ATSes, how to read the not_applied outcome, retry safety, and what is returned—everything needed to call it correctly and 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 mode and both identifiers are already documented; the baseline would be 3. The description adds cross-parameter semantics the schema does not: the two identifiers are alternatives, mode is scoped to this single application and never mutates account settings, and job_url re-use after a job_match_id application is prohibited.

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") and immediately explains the mechanism: resume/cover-letter rewrite, then submission on the employer's own ATS. It is unambiguously distinguished from siblings that save, skip, or prepare applications.

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

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

Explicitly states when not to use it ("Do not use it to save or skip a match; use getmattered_save_matches or getmattered_skip_matches"), names the two input paths (job_match_id from getmattered_get_matches vs job_url), and routes the agent forward to getmattered_get_applications and getmattered_approve_applications.

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

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

Annotations already declare the destructive, non-idempotent mutation profile, but the description adds substantial consequence detail: submissions go to the employer's hiring system under the user's name, consume an application credit, and cannot be withdrawn. It also explains plan/balance handling, timeout/retry safety, and duplicate-send prevention.

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

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

The description is front-loaded with the status condition and the irreversible consequence, and most sentences carry operational value. It is somewhat dense and repeats the schema's 1–25 range, but the length is justified for a high-stakes destructive action.

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

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

Covers prerequisites, consent guardrails, side effects, failure recovery, and the next step, while the output schema handles return-value details. Nothing material 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%, and the schema already documents the application_ids array, its 1–25 bound, and its source. The description reinforces the range and ties IDs to explicit approval, but it does not add new syntax or selection semantics 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?

States a specific verb and resource, defines the exact qualifying status, and distinguishes this tool from getmattered_apply and getmattered_get_applications. An agent can identify the action without opening the schema.

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

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

Explicitly says when to use it (applications waiting_for_review with the user's explicit go-ahead) and when not to use it (a job with no application yet, where getmattered_apply is correct). It also names the follow-up tool, getmattered_get_applications.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds the consequences an agent actually needs: nothing is sent to the employer, cancellation cannot be undone with these tools, and already-submitted applications are refused with a per-item explanation rather than failing the whole batch. That last detail materially changes how an agent should interpret results.

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

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

Front-loaded with the outcome, then constraints, then the sibling routing, then the next step. Six short sentences, each carrying distinct information; no filler or restatement of the tool name.

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

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

Covers the destructive, irreversible nature of the call, batch bounds, the partial-failure behavior, the sibling to use instead, and the natural follow-up. An output schema exists so return-shape explanation is correctly omitted.

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 schema already states the 1-to-25 limit and id derivation, so the description largely restates it. It does add value by tying the ids back to the workflow ('from getmattered_get_applications'), but adds no new format or ordering semantics 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?

States a specific verb and resource ('Cancel applications') plus the exact scope: applications queued to be sent or still being prepared. It also explicitly separates this from withdrawal of submitted applications, so the boundary of the operation is unambiguous from the first sentence.

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 ('Cancel only when the user asks'), when-not-to-use ('Do not use it for an application waiting for the user's review'), and names the correct alternative (getmattered_reject_applications). It also names the prerequisite retrieval tool and the follow-up 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?

Annotations already flag this as a non-read-only, non-idempotent, open-world write, but the description goes further: it discloses the public-link side effect ('publishes a link anyone can open'), the privacy default, the fact that no PDF is produced here, and that it 'adds a new draft and changes no existing resume.' The paid-plan requirement and the absence of PDF generation are behavioral facts 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 purpose lands in the first clause, then constraints, cautions, prerequisites and the next step follow in the order an agent needs them. Each sentence carries distinct information — scope, template options, privacy rule, prerequisites, sibling exclusion — 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?

For a three-parameter creation tool with an output schema, everything material is covered: what is created, what is not created (no PDF, no section parsing), privacy defaults, plan requirement, the sibling to use instead, and what the user must do next. Nothing needed to call it correctly is left to inference.

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

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

Schema description coverage is 100%, so the schema already documents template, make_public and summary_text, including the contact-detail exposure of a public link and the 50–2,000 character bounds. The description mostly restates these ('Templates: classic (default), modern or minimal', 'up to 2,000 characters'), adding little the agent could not read from the schema. Baseline 3 is the right score when structured fields do the work.

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

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

States a specific verb and resource ('Create a new editable draft in the user's resume builder') and pins down exactly what gets stored ('the text the user gives saved as its summary section'). It also defines the boundaries that distinguish it from siblings ('does not split text into experience, education or skills, and it creates no PDF'), so an agent can separate it from optimize_resume and set_resume without opening the schema.

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

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

Explicitly names the condition that disqualifies this tool ('Do not use it to rewrite or tailor a resume') and routes the agent to the correct alternative ('use getmattered_optimize_resume'). It also gives a conditional rule for make_public ('only when the user explicitly asks to share it') and a stated prerequisite ('Requires a paid plan'), covering when to use, when not to, and 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?

The description adds substantial context beyond annotations: it adds a search and changes nothing else, can be removed with the delete sibling, sends nothing to employers, and spends nothing. These details clarify the non-destructive, open-world=false behavior declared in annotations.

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

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

The description is front-loaded with the action and optional parameters, then efficiently covers side effects, exclusions, and next steps. Every sentence contributes useful routing or behavioral information.

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

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

With an output schema, annotations, and fully documented parameters, the description provides everything needed to select and invoke the tool correctly. It also routes to alternatives and follow-up tools.

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 both name and alerts_enabled. The description restates their meaning, including the fallback naming behavior and email effect, but adds no meaningful semantics beyond what the schema provides.

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

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

The description states a specific verb and resource: saving the user's current job preferences as a new named saved search. It also distinguishes the tool from getmattered_update_job_preferences and identifies getmattered_delete_saved_search as the removal path.

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 to use getmattered_update_job_preferences to change what the user is matched with, and says not to use this tool for that purpose. It also identifies the next tool to call, getmattered_list_saved_searches.

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, but the description adds the blast radius the annotations cannot convey: the action is irreversible ('This cannot be undone') and, critically, what is NOT affected ('job preferences and matches do not change'). Combined with the required confirmation-before-call guidance, this is richer behavioral context than the structured fields 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?

Front-loads the action and its side effect, then layers the ID source, the irreversibility warning, the negative scope, the alternative tool, and the follow-up in five short sentences. Every clause carries distinct information; nothing is repeated from the schema or annotations.

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

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

For a one-parameter destructive mutation this covers the full decision loop: what it does, what it destroys, what it leaves intact, when not to use it, which sibling to use instead, where the ID comes from, and what to do next. An output schema exists, so the absence of return-value explanation is not a gap.

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

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

Schema coverage is 100% for the single integer parameter, so the baseline is 3; the description goes one step further by naming the source of a valid value ('Pass saved_search_id from getmattered_list_saved_searches'), which tells the agent where the ID comes from rather than just its type. It stops short of describing failure modes for an invalid or already-deleted ID.

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 ('Delete one of the user's saved searches') plus an immediate consequence ('stop its email alerts'), which separates it cleanly from getmattered_update_saved_search and getmattered_create_saved_search. An agent can identify the operation 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-not guidance ('call it only when the user asks to delete that search, and name the search first') and names the correct alternative for the adjacent-but-different intent ('Do not use it only to turn alerts off; use getmattered_update_saved_search'). It also prescribes the preceding step (list_saved_searches) and a next step, leaving nothing to inference.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false, which is ambiguous for a drafting tool. The description resolves this precisely: "It only drafts: nothing is sent and nothing is recorded" plus "Uses the user's AI credits" – a side-effect cost the annotations cannot express.

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

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

Front-loaded with the purpose, then constraints, then the follow-up step. The final sentence largely repeats the earlier send-with-getmattered_send_follow_up instruction, so there is minor redundancy, but nothing else 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?

An output schema exists, so return values need no explanation. With one required parameter fully documented and the send/draft boundary spelled out, an agent has everything needed to call this correctly and route the 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?

Schema coverage is 100%, so the baseline is 3; the description earns extra by explaining the provenance of application_id (the two sibling tools that return it), reinforcing the schema text rather than merely restating the type.

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 ("Write a follow-up message for one application that has gone quiet") and enumerates the outputs it produces (channel, subject, text). It is clearly distinguishable from getmattered_send_follow_up, which it names and contrasts.

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 entry conditions (application has gone quiet), prerequisite inputs and where to source them (application_id from getmattered_list_due_follow_ups or getmattered_get_applications), and an explicit exclusion ("Do not use it to send the message; use getmattered_send_follow_up"). It even sequences the next step after user approval.

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

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

Goes well beyond the annotations: discloses that the rewrite REPLACES the letter saved on the application, that generation/revision consume AI credits while reading does not, that the plan may not include cover letters, and that the result is saved to the account. The replacement warning materially sharpens the destructiveHint=true flag rather than merely restating 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?

Content is valuable but the delivery is scattered: the resume-source fallback is stated twice ("Writes from the user's resume on file, or a resume they paste or attach" then again in the final sentence), and "It also works without a resume-builder document" is stranded mid-paragraph. Front-loading of the primary purpose is good, but the repetition costs it.

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 dual-mode, credit-consuming, destructive write tool, the description covers modes, cost implications, plan gating, replacement behavior, fallback sources, and the sibling to use for applying. An output schema exists, so return values need no further explanation.

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; however the description adds real semantic value the schema lacks, notably the resume source precedence chain (pasted resume_text → base resume on account → resume-builder document) and the constraint that instructions are meaningful only alongside application_id. It does not explain required-parameter combinations in one place, leaving the agent to assemble that from prose.

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 ("write a cover letter for a specific job") and immediately distinguishes its two modes: generation vs. reading an existing letter via application_id. It also explicitly names the sibling it is not ("Do not use it to apply to a job; use getmattered_apply"), so an agent can route correctly without opening any schema.

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

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

Explicit when-to-use (new letter from resume-builder doc, pasted resume, or base resume), when to switch modes (pass application_id to read; add instructions only with application_id to rewrite), and an explicit exclusion pointing to getmattered_apply. This is close to a complete decision tree for the 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 it discloses three things an agent cannot infer: a connected GetMattered account is required, the call consumes the user's AI credits, and the job gets saved to the account if not already saved. The remaining gap is retry behavior—with idempotentHint=false and credit consumption, it doesn't say whether re-calling after a failure duplicates work or burns credits again.

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 output list is front-loaded in the first sentence and the selection rule and exclusion follow in order of decision importance. It is a single dense paragraph that runs long, but nearly every clause carries actionable information 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?

With annotations, full schema coverage and an output schema covering returns, the description carries everything needed to select and invoke the tool: prerequisites, cost, side effects, input modes. Only the failure/retry and credit-cost-magnitude behavior is unaddressed.

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 earns a bump by explaining the consequence of choosing application_id (it preps an existing application and creates no new saved job) rather than merely echoing the schema's 'Replaces job_title and company_name'. It leaves job_description's effect unsurveyed, but the schema already covers it as optional/recommended.

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

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

The description gives a specific verb ('Produce interview preparation') plus an enumerated deliverable list (company insights, role questions, STAR scenarios, talking points, interviewer questions, salary prep) and names the exact inputs. It is clearly distinguished from getmattered_generate_cover_letter by an explicit exclusion.

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

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

It states both invocation paths with their tradeoffs: application_id for jobs already applied to ('no new saved job') versus job_title + company_name 'for any other job'. It also names the sibling tool to use instead for cover letters, so the agent has a when-not rule.

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

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

Annotations already cover readOnly/idempotent/non-destructive, but the description adds substantial context beyond them: it enumerates the sensitive data that is never returned (passwords, tokens, card/bank details, saved profile answers), states it sends nothing to any employer and spends no credits, and documents the readiness.nextStep contract that drives the next agent action. That is real behavioral disclosure, not a restatement of 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 and logically ordered (scope, exclusions, return fields, safety, when to call, what it is not for), but it is a dense ~200-word block that redundantly restates safety points twice ('changes nothing' then 'writes nothing, sends nothing... spends no credits') and exhaustively lists return fields that the output schema already carries.

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 and annotations cover the safety profile, so the description need not document returns in detail — yet the readiness.nextStep / next: getmattered_get_matches guidance is genuinely useful multi-step orchestration context that structured fields do not convey. Slight over-completeness on the field enumeration keeps it from a 5.

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

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

Zero parameters, so the baseline is 4. The description still confirms 'it takes no arguments,' which reassures the agent that no filtering arguments exist, but there is no parameter meaning to add 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?

Opens with a specific verb, resource and scope: 'Read only the signed-in user's own GetMattered account summary.' That scope clause alone separates it from every sibling (including getmattered_get_profile and getmattered_get_application_profile) without opening any schema.

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

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

Gives explicit trigger conditions ('Call it to show the user their plan and the applications they have left before applying') and explicit exclusions with named alternatives ('Do not use it to change anything; use getmattered_update_job_preferences, getmattered_update_application_profile, getmattered_set_resume or getmattered_update_automatic_apply_settings'). It even specifies a follow-on routing rule via readiness.nextStep and next: getmattered_get_matches.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real context beyond them: the hard scope boundary (never other users' data, passwords, tokens, payment or bank details), the privacy handling instruction for EEO and date-of-birth fields, and that no credits are spent. The only weakness is repetition – 'it changes nothing' appears twice, restating the annotation without adding information.

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 scope restriction and privacy caveats, then the return payload, then the next action – a sensible ordering. It is slightly over-long because the no-change/no-credit point is stated twice and the return enumeration is verbose even though an output schema already exists.

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

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

Covers scope, exclusions, sensitive-data handling, credit cost, and the follow-up action; since an output schema exists, the return-value summary is extra rather than required. Nothing an agent needs to invoke and act on this tool correctly is absent.

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

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

Zero parameters, so the baseline is 4; the description instead characterizes the payload an agent will receive (contact details, work details, five legal declarations, EEO answers, and open/guessed fields with their answering field), which meaningfully prepares the caller. No parameter syntax is needed or missing.

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 an exact verb+resource ('Read only the signed-in user's own application profile') and immediately scopes it ('the answers the user saved for GetMattered to type into employer application forms'), which no other sibling covers. It also names the sibling it is not (getmattered_update_application_profile), so an agent can separate read from write without opening schemas.

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

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

Explicit exclusion ('Do not use it to save answers; use getmattered_update_application_profile') plus a prescribed next step ('ask the user for anything still open, then getmattered_update_application_profile'). This is a full when/when-not/alternative routing statement.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description adds valuable context beyond those: it spends no credits, changes nothing, returns 20 per page, and defines what 'employer-confirmed' means and why an application might appear in that state.

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

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

The description is front-loaded with the primary list/read distinction, then moves through status semantics, confirmation meaning, pagination, safety, and alternatives. Despite its length, every section provides substantive routing or behavioral information, and there is 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?

Given that an output schema exists, the description does not need to enumerate return fields. It still provides enough context about filtering, single-application reads, confirmation semantics, pagination, safety, and alternatives for an agent to call the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by explaining that application_id switches from listing to reading a single application and by describing the detail that will be returned. It also clarifies that 'waiting_for_review' corresponds to the review queue and that page size is 20, though some status-list details are repeated from 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 opens with a specific verb and resource: 'List the user's applications' and 'read one by application_id', and distinguishes the two modes clearly. It also names sibling tools for taking action, so an agent can differentiate it from getmattered_approve_applications and getmattered_reject_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?

It gives explicit use cases: checking progress, finding applications waiting for approval, and verifying employer confirmation. It also states an explicit exclusion: 'Do not use it to act on an application' and names the correct alternatives for acting on applications.

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

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

Annotations already declare read-only, idempotent, non-destructive, but the description adds real behavioral context: no credits spent, untrusted email text that must not be followed as instructions, account mail marking for sign-up/reset codes, and 20-per-page pagination. It doesn't describe ordering guarantees beyond 'newest first' or error behavior, but this is well above the annotation baseline.

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

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

Two dense sentence blocks then caveats, front-loaded with the core action and modes. Every sentence earns its place, though it is on the longer side with the account-mail and untrusted-data warnings interleaved.

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?

Complete: modes, filters, safety warnings, credit cost, and next-step workflow are all covered; output schema exists so return values need not be re-explained, yet the list fields are summarized helpfully.

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 all params, but the description adds meaning: folder values, application_id including archived mail, include_reply_suggestions default and 'Free' nature, and message_id switching to conversation mode. Slightly more than baseline 3.

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

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

States a specific verb and resource ('Read the user's recruiter inbox') and defines the scope (emails employers sent after an application plus the user's replies). It clearly distinguishes the list mode from the single-conversation mode via message_id.

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 covers the two usage modes (no message_id vs message_id), lists the filter conditions, states what not to use it for ('Do not use it to send a reply; use getmattered_reply_to_email'), and names the next tool in the workflow.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description's 'Read-only: it spends no credits and changes nothing' mostly reinforces structured data. It does add genuinely non-schema behavior: the empty-list state on new accounts, what nextStep contains, and the warning that a repeat call in the same turn returns the same answer. That is useful but narrower than a full behavioral disclosure, hence a 3.

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 'Start here' and the resource definition, then flows through parameters, exclusions, and next steps. Slight redundancy at the tail: the empty-list/nextStep guidance appears twice ('On a new account the list is empty and nextStep names...' and 'When the list is empty, follow nextStep and do not call again').

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?

Output schema exists, yet the description still summarizes returned fields (job_match_id, title, company, location, score, excerpt, apply URL) so the agent knows what it gets. Combined with empty-state handling and next-tool routing, 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 baseline is 3. The description nonetheless frames parameters in workflow terms (pass up to 10 job_match_ids to read full postings, feed back the stored newestJobMatchId), which helps an agent choose parameters rather than just parse them, though most syntax detail is duplicated from 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 ('List the user's matched jobs') plus the source of the matches (GetMattered against saved preferences) and ordering (best matches first). It is clearly distinguishable from siblings like getmattered_save_matches or getmattered_update_job_preferences.

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 each usage mode: job_match_ids to read full postings, job_url for unsaved links, query/location/remote_only to narrow, after_job_match_id for incremental polling. It also names an exclusion ('Do not use it to change what the user is matched against; use getmattered_update_job_preferences') and prescribes the empty-list path and next tool (apply/save/skip).

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the cost dimension ("spends no credits") which annotations do not encode, though "changes nothing, sends nothing" largely restates readOnlyHint.

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 return fields, then usage, then the exclusion. Slightly redundant with the annotations in the "changes nothing, sends nothing" clause, but no sentence is wasted 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?

A zero-parameter read tool with an output schema and full annotation coverage needs little more; the description nonetheless previews the returned fields and routes the agent to the right sibling for adjacent needs. 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?

The tool takes zero parameters, so there is nothing to disambiguate and the baseline applies. The description correctly references no arguments, avoiding invented 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 and resource (read the signed-in GetMattered account) and enumerates what is returned: account id, display name, sign-in address. It also explicitly names the sibling it is not, getmattered_get_account, so an agent can distinguish the two without opening a schema.

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

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

Gives concrete when-to-use conditions — disambiguating two connected accounts and naming the account to the user before acting on it. It also supplies an explicit when-not clause with the correct alternative ("Do not use it for the plan, preferences or anything else; use getmattered_get_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?

Goes well beyond the annotations by disclosing that the link opens the GetMattered documents page and requires the user's sign-in, that the PDF is downloadable from there, and how the no-resume case is reported. The 'creates nothing, shares nothing, spends no credits' line reinforces rather than contradicts the readOnly/destructive 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-loads the core verb+resource in the first clause, then layers constraints and alternatives in a logical order. Slightly long — the DOCX/rendered-PDF explanation is helpful but could be tightened — yet 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?

Zero parameters, full annotation coverage, and an output schema that carries return shape, so the description's job is behavioral context — auth requirement, no-resume outcome, sibling routing — and it covers all three. Nothing an agent needs to call this correctly is absent.

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

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

The tool takes zero parameters, so the baseline is 4 and there is no parameter information the description could usefully add. Schema coverage is 100% and nothing is missing.

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: the private link to the PDF of the user's base resume, with a precise definition of 'base resume' (the one every application is tailored from). It is clearly separable from siblings like getmattered_share_resume_pdf and getmattered_set_resume without opening any schema.

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

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

Explicit exclusion: 'Do not use it to make the resume public; use getmattered_share_resume_pdf.' Also names the natural next step (getmattered_get_matches) and states the behavior when no resume exists, so the agent knows both when to call it and what to do after.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds the domain-specific guarantee that it 'spends no credits' and 'sends nothing', which is meaningful in a product where actions can cost credits. Ordering ('most urgent first') is also behavior an agent needs. Minor gap: no mention of pagination or result caps, though an output schema exists to carry return structure.

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 compact sentences: what it returns, the safety/cost guarantee, then the exclusion and next step. Front-loaded with purpose and zero 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?

A zero-param read tool with full annotation coverage and an output schema; the description covers purpose, ordering, safety, sibling exclusion and next step. Nothing an agent needs to call it correctly is missing.

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

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

Zero parameters, so the baseline is 4; the description correctly implies a no-argument call by describing the result set without referencing any input. Nothing is left ambiguous about what must be supplied.

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

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

Specific verb+resource ('List the user's applications whose follow-up is due') plus the sort order ('most urgent first') and the shape of each row. It is clearly distinguishable from the nearby follow-up tools, and the returned fields (application_id, job, company, urgency, follow-up count, next due date) make the object concrete.

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

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

Explicitly names a near-miss sibling and excludes it: 'Do not use it to see the follow-ups already sent; use getmattered_list_sent_follow_ups.' It also names the natural next step, getmattered_draft_follow_up, giving both a when-not and a when-next.

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

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

The annotations already declare readOnlyHint, idempotentHint, non-destructive behavior, and closed-world scope. The description adds useful context beyond annotations by stating it spends no credits and by naming the returned fields, though it does not discuss pagination or output limits.

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 mostly front-loaded and efficient, but the final sentence ('Next: getmattered_get_matches for the jobs that match now') repeats the preceding 'use getmattered_get_matches' guidance without adding new information. That redundancy costs some conciseness.

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, zero parameters, and annotations covering safety, the description supplies everything needed for correct invocation: purpose, returned fields, read-only/credit behavior, and the alternative tool for job matches.

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, so the parameter-semantics baseline is 4. The description correctly does not introduce nonexistent parameters and requires no parameter interpretation.

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?

Starts with a specific verb and resource: 'List the user's saved searches,' then enumerates exactly what each item contains. It clearly distinguishes itself from the matching/job-listing sibling and from create/update/delete saved-search siblings by calling out that it is a read-only listing.

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 'Do not use it to see jobs; use getmattered_get_matches' and repeats the next step to take. This gives the agent both an exclusion and the correct alternative, which is exactly what selection guidance should do.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real context beyond them: it explicitly states no credits are spent and describes pagination ('20 per page', cursor-for-older). The retry-after-error framing is genuinely useful behavioral guidance. Minor deduction because the read-only claim partly restates the annotations.

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

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

Front-loads the resource, then fields, paging, safety/cost, and routing. Dense but every sentence carries information; the trailing 'Next: getmattered_list_due_follow_ups' is mildly redundant but serves as a navigation cue.

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-optional-parameter read tool with a full annotations set and an output schema, this description covers purpose, paging, cost, failure-recovery, and sibling routing. 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% and the single cursor parameter is fully documented in the schema, so a baseline 3 applies. The description adds slight value by framing the cursor as coming 'from the previous answer' for older pages, reinforcing the paging workflow.

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

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

States a specific verb and resource ('List the follow-ups the user already sent or recorded'), the ordering ('newest first'), the fields returned, and the page size. An agent can immediately distinguish it from the sibling that lists follow-ups that are due.

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 ('call it after a timeout or an error from getmattered_send_follow_up, before sending again'), an explicit exclusion ('Do not use it to find the applications that need a follow-up now'), and names the correct alternative (getmattered_list_due_follow_ups). Nothing is left to inference.

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

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

Adds real behavioral context beyond the annotations: the rewrite is returned inline and does not mutate the account resume unless saved via getmattered_set_resume, and the call consumes AI credits and requires an authenticated account. That resolves the ambiguity left by readOnlyHint=false on an operation that persists nothing.

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?

Key facts (rewrite, returns, tailoring branch) are front-loaded and each sentence carries information, but the resume_file sentence is duplicated nearly verbatim in the schema description, and the closing lines repeat the account/cost constraints already implied earlier.

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 explanation, and the description nonetheless covers the three-way input decision (resume_text / resume_file / account default), prerequisites, cost, and the sibling that should be used instead for applying. 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%, so the schema carries the field definitions; the description still adds the fallback logic — omitting resume_text causes the tool to use the resume already on the account, and resume_file is the ChatGPT attachment path. Slight redundancy with the schema text keeps it from 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?

Specific verb+resource ('Rewrite a resume so it passes ATS screening') plus explicit outputs, and it distinguishes itself from siblings by naming getmattered_apply and getmattered_set_resume as the alternatives for applying and saving.

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 branching conditions: pass job_description to tailor to one posting, omit it for general optimization; do not use it to apply because getmattered_apply handles that. It also states prerequisites (connected account) and cost (AI credits).

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 say readOnlyHint=false and destructiveHint=false; the description adds the traits that actually matter here: nothing is sent, nothing is spent, and the recorded follow-up cannot be removed with these tools. That non-reversibility warning is exactly the kind of context annotations don't carry, and it does not conflict with destructiveHint=false since the tool creates rather than destroys.

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

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

Purpose, parameters, safety constraints, and routing are ordered sensibly with no filler sentences. The parameter enumeration is slightly redundant given the fully documented schema, but it is compact and readable.

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 needn't be explained. Combined with the permanence warning, the no-cost/no-send guarantees, and the explicit next-step pointer, an agent has everything needed to call this correctly and avoid misuse.

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 all five parameters are already documented, and the description mostly restates them (body length, channel default, recipient, subject). It does add framing value by labeling them optional and clarifying that the body is 'the text they sent' rather than generated content, but this is reinforcement rather than new semantics.

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

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

States a specific verb and a precisely scoped resource: recording a follow-up the user sent themselves, outside the app. It immediately distinguishes this from drafting or sending, and names the exact siblings that do those things.

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

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

Explicitly names the exclusion ("Do not use it to send a follow-up; use getmattered_send_follow_up") and gives a prerequisite discipline ("record only what the user says they sent"). It also routes forward to getmattered_get_inbox, so both the wrong tool and the next step are covered.

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

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

Adds real context beyond the annotations: the rewritten document overwrites the one saved on each application, nothing is sent to the employer, and the call consumes the user's AI credits. That cost and overwrite disclosure is valuable for a destructive, non-idempotent tool. It stops short of saying whether the overwrite is reversible or whether the prior version is retained.

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, then the exclusion and the next step. Every sentence carries either a scope rule, a safety fact, or a routing instruction; nothing is padding.

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 explanation, and the description covers the remaining risk surface: batching limits, mutation scope, credit cost, no external side effects, and the base-resume alternative. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and already documents all three fields, so the description repeats some of it (1-25 ids, ids from getmattered_get_applications, instructions in the user's own words). It does add a relational point the schema cannot express: one document_type plus one instructions string applies uniformly across the whole batch of application_ids.

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 ('Rewrite the tailored resume or cover letter of applications that are not sent yet') with an explicit scope qualifier. It is clearly distinguishable from the base-resume siblings (optimize_resume / set_resume) and from approve_applications, which it names.

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

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

Gives when-to-use (applications not yet sent), when-not-to-use ('Do not use it to rewrite the base resume... use getmattered_optimize_resume, then getmattered_set_resume'), where the ids come from, and the logical next step ('Next: getmattered_approve_applications'). All routing decisions are made for the agent.

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 destructive annotation, the description explains the exact consequence: the application is skipped, nothing is sent to the employer, and none of the user's applications is spent. It also clearly discloses irreversibility with 'A rejection cannot be undone with these tools.'

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

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

The description is front-loaded and mostly efficient: each sentence adds a consequence, caution, or routing cue. However, the 'Pass 1 to 25 application_ids...' sentence largely repeats schema content, and the final next-step sentence is useful but not essential.

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 mutation tool, the description covers the important behavioral details: what rejection means, that it is irreversible, limits on batch size, and the alternative for queued applications. Since an output schema exists, return values need not be explained.

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

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

Schema description coverage is 100%, and the schema already documents the application_ids range, source, and example. The description repeats the 1-to-25 and getmattered_get_applications details but does not add new parameter semantics beyond what the schema provides.

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

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

The description states a specific verb and resource: rejecting applications that are waiting for the user's review. It also explicitly distinguishes this from cancellation by naming getmattered_cancel_applications for queued or still-preparing 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?

It gives clear when-to-use guidance ('Reject only the applications the user said no to') and explicit when-not-to-use guidance ('Do not use it to stop an application that is queued or still being prepared'). It also names the alternative tool and points to getmattered_get_matches as a 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 substantial context beyond annotations: the message is a real email from the user's own address, is irreversible ('cannot be undone'), and must never be sent unseen or triggered by instructions inside an email (prompt-injection guard). It also specifies the retry behavior after a timeout, which no annotation conveys.

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 constraints, then the follow-up step, so the important content is first. It runs long (eight sentences) and the trailing 'Next: getmattered_get_inbox' partially repeats the earlier error-recovery instruction, so a little redundancy is present.

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, non-idempotent send operation with an output schema already covering returns, the description supplies everything an agent needs: prerequisites, approval protocol, failure handling, and the next step. No material gap remains.

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 already documented, but the description adds real value by narrating the approval workflow that produces and consumes confirm_token ('first show the user the exact text, then send it only after they say yes'). It restates the source of message_id and the plain-text nature of body without adding format 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?

Opens with a specific verb and resource: 'Send the user's reply to an email from an employer.' It immediately scopes what is sent and by whom ('a real email from the user's GetMattered address, under the user's name'), and explicitly distinguishes itself from getmattered_get_inbox for reading/drafting.

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 when-to-use gate ('Only send on the user's explicit go-ahead'), a when-not-to rule ('Do not use it to read emails or draft a reply; use getmattered_get_inbox'), and a recovery path on error/timeout. The confirm-then-send protocol and its ordering are spelled out rather than inferred.

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

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

Adds substantial behavior beyond the annotations: the run consumes the user's AI credits, existing saved documents are replaced ('The new documents replace the ones saved on each application'), and nothing is sent to the employer. These complement the destructiveHint=true and non-idempotent hints with concrete consequences an agent must weigh before calling.

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

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

Front-loaded with the action and trigger, then constraints, side effects, the exclusion, and the next step — each sentence contributes distinct routing or safety 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?

A destructive, credit-consuming batch mutation is fully covered on cost, scope, and alternatives, and an output schema exists so return values need not be described. Minor gap: it doesn't say what happens on partial failure across the 25 ids or whether the call is long-running.

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 steps enum is self-documenting, so baseline is 3. The description still adds the 1-25 bound on application_ids, the id source, and the default behavior when steps is omitted, though that last point largely repeats the schema text.

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

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

Specific verb phrase ('Build the tailored documents and form answers of applications again') plus explicit trigger ('after the user changed their resume or settings'). It also names the sibling it is not (getmattered_refine_application_documents), so an agent can separate it from refinement without reading 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 the when (after resume/settings changes), the when-not with a named alternative ('Do not use it to change one document from instructions; use getmattered_refine_application_documents'), an input constraint (1 to 25 ids from getmattered_get_applications), and a follow-up step. Nothing about routing is left to inference.

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

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

Adds behavior beyond the annotations: closed postings cannot be restored and the response reports that, nothing is sent to any employer, nothing is spent, and the action is reversible via getmattered_skip_matches. This complements idempotentHint/destructiveHint=false with concrete consequence detail.

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

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

Four short sentences in a front-loaded sequence: effect, input, constraints/safety, exclusion, next step. Nothing is redundant.

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 mutation with an output schema and full annotation coverage, the description supplies everything an agent needs: source of ids, batch limit, failure case, side effects, reversibility, and sibling 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 coverage is 100% and the schema already documents the array of ids with the same '1 to 25' bound and the getmattered_get_matches source, so the description largely restates it. No additional format or error-handling semantics for individual ids are given.

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 plus resource ('Bring back job matches the user skipped') with an explicit outcome ('show in the user's matches again'). It is clearly distinguishable from the inverse sibling getmattered_skip_matches and from getmattered_save_matches, which it names.

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

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

States input provenance ('job_match_ids from getmattered_get_matches'), the allowed batch size (1 to 25), an explicit exclusion ('Do not use it to save a match for later; use getmattered_save_matches'), and a follow-up step ('Next: getmattered_get_matches'). No inference needed.

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, idempotentHint=true and destructiveHint=false, and the description reinforces this with concrete consequences: no message reaches an employer and nothing is spent, and the action is reversible via getmattered_unsave_matches. It does not cover failure modes (invalid or already-saved IDs beyond the idempotent hint) or partial-batch behavior, which keeps it below 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-loads the action and purpose, then batches limits, safety, undo, and next step in short sentences. Slightly redundant between 'Saving does not apply' and 'Do not use it to apply', which costs a point but not readability.

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

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

An output schema exists so return values need not be described. For a one-parameter, non-destructive save operation, the description covers source of IDs, batch limits, side effects, reversibility, and the logical next call — everything an agent needs to invoke it correctly.

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

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

Schema description coverage is 100% and the single parameter already documents the 1–25 range, the source tool, and an example array. The description's 'Pass 1 to 25 job_match_ids from getmattered_get_matches' largely restates the schema, so the baseline of 3 applies despite the count constraint being repeated for emphasis.

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 ('Save job matches to the user's saved list') plus the intent behind it ('so they can come back to them'). It also names the source tool for the IDs, so an agent can distinguish it from getmattered_apply, getmattered_skip_matches, and getmattered_unsave_matches without opening any schema.

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

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

Explicit when-to-use (save matches for later), explicit when-not ('Do not use it to apply; use getmattered_apply'), a named alternative, a follow-up call ('getmattered_get_matches with saved_only'), and the undo path. Nothing about tool selection is left to inference.

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

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

Adds context beyond the annotations: no mutation of the user's resume or settings, requires a connected GetMattered account, and consumes the user's credits — which usefully explains why readOnlyHint is false for an otherwise non-mutating tool. It does not cover credit cost magnitude, failure modes, or latency, so it falls short of full behavioral 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?

Front-loaded with purpose and the targeted-vs-general branch before the caveats, which is the right ordering. Slightly redundant: the getmattered_optimize_resume handoff is stated twice ("Do not use it to rewrite... use getmattered_optimize_resume" then "Next: getmattered_optimize_resume rewrites...").

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 covers the return shape, annotations cover the safety profile, and all three parameters are fully described in the schema. The description fills the remaining agent-relevant gaps: auth/credit requirements, the no-side-effects guarantee, and the sibling 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 baseline is 3. The description clarifies the conversational origin of resume_text (pasted/attached in chat) and that omitting it falls back to the account resume, but it restates schema content and never states precedence when both resume_text and resume_file are supplied.

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") plus the exact output contents (overall score, section scores, matched/missing keywords, rewrite suggestions). It explicitly distinguishes itself from getmattered_optimize_resume, so an agent can pick the right tool 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 an explicit when-branch (pass job_description to score against a posting vs. omit for general ATS readiness), a when-not ("Do not use it to rewrite the resume"), and names the correct alternative and logical next step (getmattered_optimize_resume). 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 declare destructive/openWorld/non-idempotent, but the description adds the critical detail that a real email goes to the `to` address and cannot be undone, that a connected Gmail/Outlook is required or nothing is sent, and that confirm_token is single-use with a 10-minute window. This directly expands on the hint profile with operational safety 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?

Front-loaded with the core action and its irreversibility, then layered with guardrails and alternatives. It is dense but nearly every sentence carries procedural value; only the trailing 'Next: getmattered_get_inbox' pointer is borderline optional.

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 send tool the description covers prerequisites (connected mailbox), the confirmation flow, failure recovery, and the recording side effect; with an output schema present, return values need no explanation. 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 schema already documents every parameter including the confirm_token lifecycle and body length bounds. The description mostly restates those constraints ('to ... never a guess', 'subject and body ... the exact text the user approved') rather than adding syntax or format guidance beyond the schema, so it sits at the high-coverage baseline.

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

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

Specific verb+resource: sends a real follow-up email about one application via the user's Gmail/Outlook under the user's name, then records it. It explicitly distinguishes itself from getmattered_reply_to_email, getmattered_draft_follow_up and getmattered_record_follow_up, so an agent can route correctly without opening schemas.

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

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

Gives explicit when-to-use (only on the user's explicit go-ahead after showing exact subject and body), when-not (do not use to answer an employer's email – use reply_to_email), and fallbacks (no connected account → record_follow_up; timeout/error → list_sent_follow_ups before retrying). Nothing is left to inference.

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

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

Adds real context beyond the annotations: it changes only the stage field, nothing is transmitted to the employer, and it can be re-run (consistent with idempotentHint=true). It stops short of stating behavior on partial failure (e.g., what happens if some of the 25 ids are invalid or not owned by the user).

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

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

Front-loaded with the core action and stage values, then the constraint, then the exclusions — a sensible order. Slightly wasteful in re-listing the seven enum values that the schema already documents twice.

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 annotations covering safety profile, the description supplies exactly the missing pieces: sourcing of ids, sourcing of stage values from the user, non-employer-visible side effects, and sibling disambiguation. 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 schema already carries the mechanics; the description adds provenance for application_ids ('from getmattered_get_applications') and reinforces the 1-to-25 bound. The stage list is repeated from the schema enum and description, so it adds little there.

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 ('Record how applications are going') and enumerates the exact stage values being written. It explicitly separates itself from the closely overlapping siblings approve/reject/cancel, which matters because 'rejected' also appears in this tool's own enum.

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 conditions ('Do not use it to approve, reject or cancel an application') and names the exact alternative tools to use instead. It also adds a data-sourcing rule ('Set it only from what the user tells you') and a next-step pointer to getmattered_generate_interview_questions.

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=true, idempotentHint=false) by disclosing the actual cost model (~300 AI tokens out of 10,000, document_id path free), the replacement semantic that the old resume is retained in documents, the side effect of finishing account setup and starting job discovery, and the ChatGPT file-attachment download behavior. That is precisely the mutation/side-effect context the annotations only hint at.

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

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

Front-loaded with the action and the mutual-exclusion rule before cost and routing details. Seven sentences is on the long side, but each carries distinct information (cost, setup completion, exclusions, next step, ChatGPT path, replacement semantics) 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?

An output schema exists, so return values need not be explained. For a destructive, open-world, non-idempotent mutation with four optional mutually exclusive params, the description supplies prerequisites, cost, side effects, exclusions, and follow-up – nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real value by stating the exclusive-or constraint ('Pass exactly one') and by attaching differing costs to different argument paths (new upload costs tokens, document_id is free). It does not extend the schema's file-type/size limits beyond what is already documented there, 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?

States a specific verb and resource ('Put the user's resume on their GetMattered account as the base every application is tailored from') and immediately clarifies the concept of a 'base resume'. Explicitly names the siblings it is not (getmattered_optimize_resume, getmattered_score_resume), so the agent can select it without opening the schema.

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

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

Gives concrete trigger conditions ('when getmattered_get_account shows no resume on file, or when the user gives a new one'), explicit exclusions for rewrite/score work, a caution that it should only be called when the user wants this resume used, and a next-step pointer (getmattered_get_matches). This is about as complete as usage guidance gets.

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

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

The description adds substantial context beyond the annotations: the link is public, anyone with it can view contact details without signing in, sharing can later be turned off, and nothing is sent to employers or spent. This is consistent with the annotations, including readOnlyHint=false, openWorldHint=true, and destructiveHint=false.

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

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

The description is front-loaded with the core action and public-visibility consequence, then adds usage constraints, the alternative tool, and a post-call instruction. Each sentence contributes relevant guidance without 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 zero-parameter schema, existing output schema, and annotations, the description covers the action, privacy implications, usage boundaries, reversibility, and expected next step. Nothing essential for correct invocation appears to be missing.

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

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

There are no input parameters, so there is no parameter semantics to explain beyond what the schema already conveys. The baseline for a zero-parameter tool is 4.

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: turning on a public share link for the PDF of the user's base resume, and returning it. It also explicitly distinguishes this from getmattered_get_resume_pdf_link, so an agent can select the right tool without schema inspection.

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

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

It gives a clear when-to-use condition ('only when the user explicitly asks to share their resume publicly') and a clear when-not-to-use case ('Do not use it only to download the resume'), naming the alternative tool to use instead.

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

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

Goes well beyond the annotations by disclosing side effects and safety context an agent could not infer: nothing is sent to any employer, nothing is spent, and the reason is persisted and used to improve future matches. It also documents reversibility and the condition under which undo works (while the posting is still open), which complements idempotentHint=true and destructiveHint=false rather than restating 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?

Front-loaded with the action and effect, then constraints, then alternatives, then the next step — a sensible ordering with no filler. It loses a point for duplicating structured data verbatim (the 1-to-25 range and the full reason enum list already live in 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 two-parameter mutation with full schema coverage, an output schema, and annotations, the description supplies exactly the missing pieces: cost/notification side effects, reason persistence, reversibility, and sibling routing. An agent has everything needed to decide and call correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by explaining where the ids come from (getmattered_get_matches) and, more importantly, what the reason field actually does downstream (saved with the skip, trains the matcher). It restates the batch size and enum values that already exist in the schema, 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?

States a specific verb and resource (skip job matches) plus the observable effect: they stop showing in the user's matches. It is clearly distinguished from nearby siblings by naming getmattered_restore_matches as the undo and getmattered_reject_applications as the wrong tool for a different situation.

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

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

Explicitly says when to use it ('Skip only the matches the user turned down'), when not to ('Do not use it to reject an application that is waiting for review'), and which alternative to use instead. It also names the follow-up step: getmattered_get_matches for the next matches.

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 important behavior beyond the annotations: the translation is saved as a separate resume, the original stays unchanged, the tool uses the user's AI credits, and it returns a title and link. These details are consistent with the non-read-only, non-destructive, non-idempotent 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 key purpose, output behavior, and alternatives are front-loaded and easy to scan. There is some repetition about resume sources and working without a builder document, but the length is justified by the tool's multiple input paths.

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 and high schema coverage, the description is complete enough for correct invocation: it covers source selection, file handling, credit usage, output behavior, and when to use a sibling tool instead.

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 already documented. The description still adds useful meaning by specifying source precedence: pasted/attached resume text first, then the account's base resume, then the resume-builder document, and by clarifying when to pass resume_file.

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: translating a resume-builder document into another language. It also clarifies the source-document fallback behavior and distinguishes the tool from resume tailoring by naming siblings getmattered_optimize_resume and getmattered_apply.

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 not to use this tool (to tailor a resume to a job) and names the alternatives. It also explains when it works without a resume-builder document and gives source precedence for pasted/attached resumes.

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

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

Goes well beyond the annotations by disclosing real-world side effects: nothing is sent to an employer, nothing is spent, and the action is reversible via save_matches. This concretely reinforces the destructiveHint=false and idempotentHint=true annotations with domain-specific meaning.

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?

Short, front-loaded sentences with no filler; the safety and routing information comes early. The trailing 'Next:' sentence is a useful but slightly clipped navigation cue that breaks the prose 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?

For a single-parameter, non-destructive mutation with full annotations and an output schema, the description covers purpose, input source, side effects, reversibility, and the alternative tool. Nothing an agent needs to invoke it correctly is absent.

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

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

Schema description coverage is 100% and the single parameter is already fully documented in the schema, including the 1-to-25 bound and example format. The description restates the same constraint and source tool, adding no new syntax or edge-case guidance, so baseline 3 applies.

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

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

States a specific verb and resource ('Remove job matches from the user's saved list') and immediately clarifies the scope: matches remain in the user's matches. This distinguishes it from save_matches, restore_matches, and skip_matches named in the siblings list.

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

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

Explicitly names the anti-pattern ('Do not use it to hide a match the user does not want') and routes to the correct alternative, getmattered_skip_matches. It also states input provenance (ids from get_mattered_get_matches), the reversal path (save_matches), and the follow-up 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?

Annotations declare readOnly=false, destructive=true, idempotent=true, but the description goes well beyond them: nothing is sent to employers, no credits spent, no other user's data touched, a saved answer replaces the previous value and is not kept, and undo is only possible by re-saving the earlier value. That last point is exactly the destructiveBehavour an agent needs to warn a user about, and it is consistent with destructiveHint=true rather than contradicting it.

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

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

Front-loaded with the mutating scope and safety boundaries before the field inventory, and most sentences carry distinct information. It runs long, and the exhaustive enumeration of 33 field names duplicates a schema that is already at 100% coverage, which is the one place text does not fully earn 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?

An output schema exists, and the description still tells the agent what comes back ('reads the profile back... and returns the profile and the questions still open'), which is the operationally relevant part. Combined with the mutation warnings, read-back behavior and next-step routing, nothing material is missing for a 33-parameter write 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 semantic value: null clears a saved answer, values must come verbatim from the user's conversation rather than being inferred from a resume, name or photo, and the EEO/legal/date_of_birth fields are flagged optional-and-sensitive with prefer_not_to_say as an accepted value. The grouped field inventory (contact / work / legal / EEO) is useful orientation, though it largely restates what the schema already enumerates.

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 with explicit scope: 'Change only the signed-in user's own application profile, the answers GetMattered types into employer application forms.' It immediately delimits blast radius ('no other saved answer, resume, job preference or setting changes') and names the sibling it is not (getmattered_get_application_profile).

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

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

Provides both when-to-use and when-not-to-use: 'Do not use it to read the profile; use getmattered_get_application_profile.' It also adds invocation preconditions ('Pass at least one field, and only values the user stated in this conversation') and routes to next steps (get_matches or apply).

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 destructiveHint=true annotation by explaining that "auto" sends applications in the user's name with no confirmation and that a sent application cannot be undone, while settings themselves are reversible. It also discloses plan gating (Hired Yesterday required to turn Auto Apply on, otherwise the response reports the failure and nothing changes) and that the call returns the settings after the change.

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

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

Front-loads the purpose and the destructive "auto" semantics, and every sentence carries information an agent needs. It is dense and long for a four-optional-parameter setter, and the ordering jumps between semantics, gating, and next steps, so structure could be tighter.

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

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

Covers the mutation's irreversibility, plan prerequisite, return behavior, and sibling routing; since an output schema exists, return-value detail need not be spelled out. An agent has everything needed to decide whether and how to call it.

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

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

Schema coverage is 100%, so the per-parameter meanings are already documented; the description adds real value by tying default_apply_mode to the behavior of getmattered_apply when its mode is omitted, which the schema does not say. It does not add anything further about match_level thresholds or the plan cap on daily_limit beyond what the schema already states.

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?

Names the exact resource (Auto Apply settings) and enumerates the four settings it changes (enabled, default_apply_mode, daily_limit, match_level), so an agent knows precisely what is mutated. It also explicitly contrasts itself with getmattered_apply for single-job 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 both a positive gate ("Call it only when the user asks to change these settings, never on your own") and an explicit exclusion with the correct alternative ("Do not use it to apply to one job; use getmattered_apply"). It also names the natural follow-up tool, getmattered_get_applications.

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 destructiveHint=true by explaining exactly what is lost: lists REPLACE saved values, previous lists are not kept, and undo requires re-saving the earlier values. It also discloses a cost not visible in annotations ('Uses AI credits' for the description field) and a data-integrity rule ('fill only values the user stated, never guesses').

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 re-run side effect, then prerequisites and cautions in a logical order. It is dense and runs long for a single description, and the mixed enumeration of fields partly duplicates the schema, but nearly every sentence carries actionable information.

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

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

For a 15-parameter, nested-object, destructive mutation with an output schema, the description covers the missing pieces: implicit full re-run of discovery, replace-not-merge list semantics, no history/undo, credit consumption, and the read-before-write workflow. An agent has enough to call it safely without guessing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra by documenting precedence that the schema does not ('fields passed explicitly win over it') and by glossing the plain-words description field with a realistic example. It doesn't add resolution detail for the salary/currency pairing beyond what the schema already states, so not a 5.

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

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

Opens with a specific verb+resource+outcome ('Set what GetMattered hunts for ... and re-run discovery immediately') and then enumerates the exact preference fields it governs. It explicitly separates itself from getmattered_get_account (read current prefs) and getmattered_get_matches (search), so an agent can route correctly without opening any schema.

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

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

Gives an explicit gate ('Only call this when the user asks'), a prerequisite ('Read the current preferences first with getmattered_get_account'), and a hard exclusion with the correct alternative ('Do not use it to search; use getmattered_get_matches with query'). This is the when/when-not/alternative triad done fully.

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 idempotent, non-destructive, and non-read-only behavior. The description adds meaningful context beyond annotations: only passed fields change, changes are reversible, roles and locations are preserved, and no employer communication or spending occurs.

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 action is front-loaded, and every sentence contributes new information: partial-update behavior, reversibility, invariants, exclusions, and the next step. There is no redundant restatement of 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 low-complexity mutation with full schema coverage, rich annotations, and an output schema, the description provides everything needed to invoke it correctly and avoid the nearest misuse case.

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 all three parameters. The description still adds useful semantics: saved_search_id comes from getmattered_list_saved_searches, name and alerts_enabled are optional and can be combined, and only supplied fields are updated.

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 specific actions (rename, turn email alerts on/off) on a specific resource (saved search). It also distinguishes this tool from getmattered_update_job_preferences, so an agent can tell it apart from a similarly named 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?

It says exactly what to pass: saved_search_id from getmattered_list_saved_searches plus name, alerts_enabled, or both. It also gives an explicit exclusion ('Do not use it to change the job preferences') and names the correct alternative tool.

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