career

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

With no supporting annotations, the description carries the disclosure burden. It explains the generation source, the output format, the bracketed-prompt behavior, and the privacy rule that posting content is not restated as the user's. It does not cover failure modes or overwrite semantics, but those are partially documented in parameters.

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

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

Three sentences deliver the core action, output behavior, privacy constraint, and quota. Every sentence adds distinct information with no filler, and the primary action is front-loaded.

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

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

For a tool with 8 parameters and no output schema, the description provides a solid summary of the artifact, source, return values, and an important constraint. It could be more complete by explaining what happens if no profile exists or by routing users to a sibling tool for resume generation, but the essentials are present.

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

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

The schema already documents 5 of 8 parameters, so the description does not need to restate them. It adds useful context about 'bracketed prompts' and the no-restatement rule, but it does not explain company, role, or hiring_manager. Overall it neither strongly compensates for the missing schema coverage nor repeats schema details excessively.

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

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

The description names a specific verb and resource: 'write a one-page cover letter .docx' and clarifies the source ('from the stored profile') and the return value ('path, word count and bracketed prompts'). This clearly separates it from resume-focused siblings like resume_create and resume_read.

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 the clear trigger: 'Call this tool to write a one-page cover letter .docx.' This gives the agent a direct condition for use. It does not explicitly name alternatives or exclusions, but the purpose is specific enough to avoid obvious sibling confusion.

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

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

With no annotations, the description carries the burden of behavioral disclosure, and it does well: it explains the 'without .docx' naming requirement, scopes deletion to the user's token, and explicitly states that unknown names are refused with nothing deleted. It does not mention whether deletion is permanent or what the success response looks like, but overall it is transparent.

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 short sentences deliver the action, parameter semantics, and failure behavior with no filler. The most important usage constraint (no .docx) is front-loaded.

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

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

For a single-parameter delete operation with no output schema, the description is complete: it explains what is deleted, how to identify it, where to find valid names, and what happens on failure. No critical information 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 0%, so the description must fully explain the sole parameter. It does: 'name is the name it was uploaded under, without .docx' and 'doc_files lists them.' This adds crucial formatting and sourcing context beyond the raw schema.

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

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

The description states a specific action ('Delete one document uploaded for your token') and identifies the target resource precisely. It also clarifies the naming convention (without .docx), which distinguishes it from sibling upload/create tools.

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

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

The description clearly indicates when to use this tool—to delete an uploaded document—and points to doc_files as the way to list uploadable names. It does not explicitly state when not to use it or name alternatives, so it falls just short of a full 5.

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

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

With no annotations, the description carries the burden. 'List' implies a read-only operation with no side effects, which is transparent enough for a list function.

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 one concise sentence that fully conveys the purpose without unnecessary detail.

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

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

Given no parameters and no output schema, the description fully covers what an agent needs to know to invoke this tool correctly.

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

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

There are zero parameters, so the baseline of 4 applies. No additional parameter context is needed.

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

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

The description clearly states the verb 'list' and the resource 'documents' with sizes, distinguishing it from sibling tools like doc_upload and doc_delete_upload.

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 is implicitly clear that this tool should be used when the user needs to see uploaded documents, though no explicit alternatives are mentioned. The simplicity of the operation makes this adequate.

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?

No annotations are provided, so the description carries full burden. It states that files are stored under a given name and can be removed via doc_delete_upload, which gives some behavioral info. However, it does not mention potential side effects like overwriting an existing name, authentication requirements, or rate limits. It is average but not exhaustive.

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 detailed but not excessively verbose. It repeats the url explanation (once in the description and once in the schema), which adds a little redundancy, but overall it is well-structured and conveys necessary info efficiently.

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

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

Given the tool's simplicity and no output schema, the description covers what happens after upload (stored under name, removable) and the lifetime (kept for token). It lacks explicit mention of error cases or return values, but for this scope it is sufficiently complete.

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%: all three parameters (url, name, docx_base64) have meaningful descriptions. The description also clarifies the 'name' parameter's format and purpose. This fully explains how to use each parameter without ambiguity.

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

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

The description clearly states the tool uploads a .docx file to the endpoint for later use, distinguishing it from sibling tools like doc_delete_upload and doc_read. It explicitly says 'Send an existing Word document to this hosted endpoint', which is a specific verb and resource.

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 explains when to use it (to get a document ready for other tools) and provides guidance on choosing between base64 and url, including a recommendation for large files. It also mentions that uploads are kept for the token, implying a session context. No explicit comparison to alternatives, but the context is clear enough.

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 indicate this is not read-only and not destructive, and the description adds useful behavioral detail: existing data under the token stays, and a wrong or expired key changes nothing. This goes beyond the annotation hints by explaining failure semantics and safety of the operation.

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

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

The description is two sentences with no filler. It front-loads the core action, then gives the key format and safety guarantees, and closes with the verification tool. Every sentence contributes essential 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 single-parameter activation tool with annotations covering the safety profile, the description is complete: it states what the tool does, what input is needed, what happens on failure, and how to confirm success. There is no missing critical information for an agent to call it correctly.

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

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

The schema already documents the key parameter and its format with 100% coverage. The description adds meaning by specifying that the key must be issued at checkout for this server or the bundle, which clarifies validity requirements not present in the schema.

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

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

The description uses a specific verb and resource: it 'turns Pro on' for the connection using a license key. It also distinguishes itself from the sibling license_status tool by saying license_status confirms the activation. This leaves no ambiguity about what the tool accomplishes.

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

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

The description provides clear context for use: the key must be an MCPL1.<payload>.<signature> issued at checkout for this server or the bundle. It does not explicitly list exclusions or alternative tools, but it does reference license_status as the confirmation path, giving the agent a sense of 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, idempotentHint, and destructiveHint. The description adds useful context beyond annotations by specifying the JSON response contents and stating 'nothing changes,' reinforcing the read-only nature of the call.

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 sentences cover output, purpose, usage context, and side-effect guarantee. Every sentence earns its place and the most important information is front-loaded.

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

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

With no output schema, the description sufficiently describes the return value. With no parameters, annotations covering safety, and a clear use case, nothing essential is missing for an agent to invoke this tool correctly.

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

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

There are zero parameters and the schema already fully documents that fact. The description explicitly says 'No arguments,' which is accurate and reinforces the schema without needing further elaboration.

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 begins with a specific verb ('Report') and a precise resource ('this endpoint's licence state for your token'), and enumerates the exact output fields: product, tier, reason, and checkout URL. This clearly distinguishes it from sibling tools like license_activate.

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

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

The description explicitly states when to call it: 'Call it to explain a free-tier refusal.' This is clear contextual guidance, though it does not name alternatives or explicitly state when not to use it.

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

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

Annotations already safely mark this as read-only, idempotent, and non-destructive. The description adds useful behavior beyond that: it returns the canonical profile exactly as downstream generation tools will see it, including the resolved variant and every stored variant name. Since there is no output schema, this return-content disclosure is valuable and does not contradict the annotations.

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

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

The description is two sentences long, front-loads the core behavior, and adds a clear call-to-action ('Call it before any rewrite') with no filler. Every clause earns its place.

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

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

The description covers what is returned and when to call it, which is good given the simple read-only nature of the tool. However, because there is no output schema and parameter coverage is zero, the missing explanation of the optional variant selection and the meaning of 'the variant read' leaves an important 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 description coverage is 0%, so the description must explain the optional 'variant' parameter. It mentions 'the variant read' and 'every stored variant name,' but never explicitly states how passing a variant affects the result or what happens when it is omitted. The only parameter's semantics remain under-specified.

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

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

The description names a specific verb ('Return') and a concrete resource ('the stored CV profile'), then specifies exactly how it will be used: 'exactly as resume_create, cover_letter_create and tailor_to_job will use it.' It also distinguishes itself from related read/write siblings by calling out the additional variant information and the dependencies on those generators.

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

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

The description gives an explicit when-to-use instruction: 'Call it before any rewrite.' This is clear, practical context for an agent deciding whether to invoke it. It does not name exclusions or directly compare against alternative tools like profile_set or resume_read, so it falls just short of the highest score.

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

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

With no meaningful annotations (readOnlyHint=false, destructiveHint=false, no safety guidance), the description carries the full burden of disclosing behavioral traits. It only says 'Store' and mentions a return count; it omits that an existing profile requires merge or replace, that roles are re-sorted newest-first, and that omitted fields fall back to a shared business profile. These details exist in the schema, but the description itself does not disclose them.

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

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

The description is one efficient sentence that front-loads the core action and resource, lists the stored content, and closes with the return value. Every clause earns its place, and nothing is redundant with the title.

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

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

Given the high complexity (15 parameters), absent output schema, and blank annotations, the description is minimally adequate: it explains the store operation and return count but leaves key behavioral context (merge/replace handling, profile defaults, sorting) to the schema. It is enough for invocation only because the schema descriptions are unusually rich.

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 67%, and the schema already provides rich parameter semantics such as merge/replace requirements, email fallback behavior, experience sorting, and Pro-only fields. The description adds high-level content categories but no parameter-specific meaning, which is acceptable but not compensatory for the remaining undocumented parameters.

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

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

The description uses a specific verb ('Store') with a clear resource (the profile used by resumes and cover letters) and enumerates the contained sections: contact details, summary, skills, roles, education, certifications, and languages. This clearly distinguishes profile_set from its sibling profile_get, which reads the profile rather than storing it.

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

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

The description states the contextual purpose: this is the profile 'every resume and cover letter is built from,' so an agent can infer this is the setup step before generation tools like resume_create or cover_letter_create. It does not explicitly name alternatives or give when-not-to-use guidance, so it falls just short of a 5.

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

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

Annotations provide no hints (all false), so the description must carry behavioral disclosure. It does by noting the tool writes a file and returns the output path, estimated page count, dropped bullets, and keyword match/missing status, revealing potential bullet trimming. It doesn't cover failure modes like existing file conflicts, though the schema covers the overwrite flag.

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

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

A single, front-loaded sentence states the action and enumerates the return values with no wasted words. It efficiently conveys the tool's purpose and outputs.

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

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

With no output schema, the description must explain return values, and it does by listing the output path, page count, dropped bullets, and keyword status. It also makes clear it uses the stored profile. It doesn't mention error handling, but the schema covers overwrite and defaults, making this adequate for a creation 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 description coverage is 86%, so the schema already documents most parameters. The description adds no additional parameter meaning, only behavioral context about return values. It stays at the baseline for high schema coverage.

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

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

The description states the specific action 'write the stored profile to a Word .docx', identifying both the verb and the resource. This clearly distinguishes it from siblings like resume_read or resume_to_markdown, which read or convert rather than create a new docx.

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

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

The description does not explicitly mention alternatives or provide when-to-use guidance. It implies this is the tool for creating a .docx resume, but doesn't contrast it with resume_to_html or resume_to_markdown, leaving the agent to infer the 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the save flag behavior (saves only if true) and the refusal of .doc/.rtf formats, which are not in the annotations. No contradiction with annotations.

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

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

The description is two sentences, with the primary purpose stated first and the safety/constraint note second. Every clause carries information: the action, the output shape, the save behavior, and the file format restriction. No redundancy or 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?

There is no output schema, but the description gives a partial picture of the return: 'into the profile shape, with the sections found and anything unplaced.' This is sufficient for an agent to understand the general outcome. It does not cover error handling or the exact JSON structure, but for a read operation with clear annotations, this is reasonably complete.

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 75%, leaving 'variant' undocumented. The description does not explain 'variant' at all, nor does it clarify the relationship between 'path' and 'docx_base64' (e.g., whether they are alternatives or mutually exclusive). The description does reinforce that docx_base64 is the .docx itself, but the gap on 'variant' is not compensated.

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

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

The description clearly states a specific verb and resource: 'read an existing .docx resume into the profile shape.' It explicitly mentions the output (sections found, anything unplaced) and implicitly differentiates from sibling tools like resume_create (creation) and resume_to_html/markdown (conversion). No ambiguity about what this tool does.

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

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

The description provides clear context: use it to read an existing .docx resume, and it explicitly warns that nothing is saved unless save=true, advising review first. It also specifies that .doc and .rtf are refused, which is a key constraint. It does not explicitly name alternative tools or when not to use it, but the purpose is clear enough that an agent can infer the appropriate scenario.

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

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

Annotations provide no safety hints (readOnlyHint=false, destructiveHint=false, etc.), so the description carries the burden. It discloses that the tool writes a file, returns the path, and trims bullets to fit max_pages. It also notes 'Free' (likely cost). These are useful behavioral traits beyond the structured fields.

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

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

The description is brief (three sentences) and front-loads the core action. The extra note about printing to PDF and the 'Free' tag are arguably useful, though 'Free' is terse and could be placed better. Overall, it is concise without waste.

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

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

For a tool with 5 parameters and no output schema, the description is incomplete. It does not explain the return value format beyond 'where it went', does not describe the variant or target_role parameters, and omits failure behavior (e.g., when out_path exists and overwrite is false). The schema covers some params, but the description does not fill the remaining gaps.

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

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

Schema coverage is 60% (out_path, max_pages, overwrite have descriptions; variant and target_role do not). The description adds meaning for max_pages ('bullets are trimmed to fit max_pages') and implicitly for out_path via 'return where it went', but it does not address variant or target_role at all. It partially compensates but leaves gaps.

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 the action (write the resume as semantic HTML) and the resource (resume) with a print stylesheet, and notes it returns the location. It is clear about the output format and the printing workflow, though it does not explicitly differentiate from resume_to_markdown or other siblings. The mention of 'there is no doc_to_pdf here' provides some context but not a direct sibling comparison.

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

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

The description instructs to call the tool for HTML output and mentions printing to PDF from a browser, and that doc_to_pdf is unavailable. However, it does not specify when not to use it, nor does it mention the sibling resume_to_markdown or other alternatives. The guidance is present but incomplete.

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

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

The description adds meaningful behavioral details beyond the all-false annotations: 'Nothing is written to disk' clarifies side effects, and 'Same page-budget trimming as resume_create for max_pages' explains how max_pages influences output. The 'Free' note also adds a practical constraint. No annotation contradiction is present; readOnlyHint=false is an absence of a hint rather than an explicit claim that the tool mutates 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?

Three short sentences front-load the core purpose, then add the paste use case, max_pages behavior, and side-effect/cost guarantees. Every sentence contributes information without repetition or 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?

The tool's core output and side-effect behavior are well covered, and the return format is stated inline. However, with no output schema and no descriptions for variant and target_role, the definition is incomplete for an agent that needs to invoke it with non-default optional parameters.

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 schema description coverage at 0%, the description needed to explain all three parameters. It only indirectly explains max_pages via 'Same page-budget trimming as resume_create for max_pages,' and leaves variant and target_role completely unexplained. An agent cannot determine what values to pass or what these parameters do.

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: 'Return the stored profile as markdown text inline.' It clearly states the output format (markdown), which differentiates it from sibling resume_to_html, and identifies the paste-ready use case. There is no ambiguity about what the tool produces.

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

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

The description gives a clear context for use ('ready to paste into a form or an ATS box') and references resume_create for max_pages trimming behavior. It does not explicitly contrast this tool with resume_to_html, resume_read, or profile_get, so the when-not-to-use guidance is left to inference.

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

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

The description explicitly and prominently discloses read-only behavior: 'writes nothing, changes nothing.' This is especially valuable because annotations do not assert readOnlyHint. It also lists the return payload components, giving the agent a clear behavioral model. Although readOnlyHint is false in annotations, this reads as an absent hint rather than a positive contradiction.

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 short and front-loaded with the most decision-relevant fact (read-only). The redundancy of 'READ-ONLY' plus 'writes nothing, changes nothing' costs a minor point, but overall every sentence earns its place and the follow-up action is stated cleanly.

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?

The description covers purpose, safety, outputs, and the next sibling to call, which is strong for a three-parameter analysis tool with no output schema. However, the variant parameter is completely unexplained, and the phrase 'facts you already stated' is vague about prerequisites or how a resume's facts are supplied. These are meaningful gaps for an agent deciding how to invoke the 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 only 67%: limit and job_description have schema descriptions, but variant has none. The description adds no parameter-level meaning and does not compensate for the undocumented variant field. The phrase 'against a posting' only echoes job_description's existing schema description rather than enriching it.

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

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

The description states a clear, specific operation: gap analysis against a job posting, with concrete outputs (matched keywords, missing ones, coverage figure, orderings). It also disambiguates from the sibling resume_create by framing that tool as the follow-up action. This is a strong, distinct purpose statement.

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

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

The description implies the context: run this analysis against a posting before acting with resume_create. It names the relevant sibling and frames the sequencing. It does not explicitly state when not to use the tool, but since no other sibling performs gap analysis, the exclusions are not necessary.

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