CVEmber

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

Annotations (destructive=true, non-idempotent, write) are consistent with "Saves... as a master", and the description adds real behavioral context the annotations cannot: duplicate detection semantics, the duplicate_resume error, and that missing details are returned in checks rather than failing. It could say more about what a master creation affects, but it is informative beyond structured data.

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

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

Three dense sentences with no filler; the core action and its main edge case (duplicate) are front-loaded before the detail about checks.

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 an 8-parameter nested write with no output schema, the description explains the duplicate outcome and where missing extracted details surface (checks), which covers the riskiest agent decisions. Gaps remain around how templateId/colorId affect the result, but nothing critical to a correct call 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 coverage is 63%, so the schema carries most of the load. The description adds meaning for sourceText ("the attachment's text as read") and role (already documented in schema), but leaves colorId, templateId, sourceKind, and the structure of content unaddressed beyond what the schema states. Baseline 3 is appropriate.

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

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

"Saves the person's resume or LinkedIn profile as a master for a role" gives a specific verb, resource, and scope, and the duplicate/checks details distinguish it from update_resume and tailor_resume. An agent can separate this from its siblings without inspecting their schemas.

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

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

It clearly frames the create case and routes the duplicate case: "Refused as duplicate_resume if that master exists: offer to update it." There is no explicit contrast with tailor_resume or update_resume for the non-duplicate path, so the alternative-selection guidance is strong but not exhaustive.

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=true, so safety is covered; the description still adds real behavioral context: the 15-minute link lifetime, the gated-access precondition, and the exact failure shape (payment_required + pricing page). It stops short of saying what the returned link looks like beyond '15-minute link', but the essentials are disclosed.

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

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

Two sentences, both front-loaded: the successful behavior first, the failure branch second. No filler, and the key constraint (expiry) appears in the opening clause.

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 read-only tool with full schema coverage, the description covers the outcome, the precondition, the expiry, and the error response. Only a note on how the link is returned to the caller would make it fully self-contained.

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 resumeId parameter is already documented there ('A resume id from list_resumes'); the description adds nothing about it. Baseline 3 applies when the schema carries the parameter burden.

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 ('downloads the resume as a PDF') plus the artifact returned ('A 15-minute link'), and names the platform. No sibling tool overlaps, so it is unambiguous which tool to pick for PDF export.

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 condition under which the tool succeeds ('when download access or an unlock covers it') and the fallback path otherwise ('answers payment_required with the pricing page'). It also rules out a related action ('nothing is bought through this tool'). No explicit alternative tool is named, but none exists among siblings.

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, and closed-world behavior, so safety is covered. The description adds valuable scope context by listing the categories of account data returned and explicitly excluding contact details, which prevents an agent from expecting contact 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?

The description is a single efficient sentence that front-loads the account-plan purpose and then lists the additional returned information. Every clause adds scope detail without redundancy.

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

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

For a zero-parameter read tool with rich annotations and no output schema, the description adequately explains what categories of account information are returned and what is excluded. It does not describe the response shape, but the content categories and exclusion are sufficient for an agent to decide whether 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?

The tool takes zero parameters, which is the baseline 4 under the scoring rules. There are no parameter semantics to clarify, and the description does not introduce misleading parameter expectations.

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 identifies the specific resource (the account) and enumerates what information it returns: plan, download access status, PDF export requirements, and connection permissions. It is clear and distinguishable from resume-focused siblings, though it does not explicitly name when a sibling like export_pdf should be preferred.

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?

Usage is implied rather than stated: an agent can infer this is for checking account plan, permissions, and export prerequisites before performing related actions. There is no explicit when-to-use, when-not-to-use, or alternative-tool routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, closed-world, so the safety profile is covered. The description still adds real value beyond them by disclosing an output quirk: a saved job ad or imported text comes back under 'foreign', which an agent would not otherwise know.

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?

One dense sentence with the payload contents listed up front and the 'foreign' caveat trailing; no filler, no restatement of annotations 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?

With no output schema, the description correctly compensates by enumerating return fields and flagging the foreign-content case. Missing only minor operational detail such as error behavior for an invalid or inaccessible resumeId.

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 resumeId parameter is documented as 'A resume id from list_resumes', so the schema does the heavy lifting. The description adds no further semantics about the id format or sourcing, matching the baseline 3 for a fully-documented single param.

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 ('One resume') and enumerates its returned contents (contact, headline, summary, experience, education, skills, projects, certifications) plus template, colour and contentVersion, which unambiguously separates it from list_resumes and the mutation siblings. The verb is only implied via the title 'Read resume' rather than stated in the description itself.

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 phrase 'One resume's full content' implies the single-record vs. list distinction, but there is no explicit when-to-use guidance, no mention of pairing with list_resumes to obtain the id, and no statement of when not to use it (e.g., use get_account for account data).

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, closed-world behavior, so the safety profile is covered. The description adds genuinely new context: result ordering (newest first), the fields each item carries, that counts are included, and that contact details are omitted — a useful privacy boundary. It stops short of describing pagination behavior despite cursor/limit 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?

A single compact passage that front-loads what is returned before listing filters; every clause carries information. Slightly run-on phrasing ("its CVEmber score and downloadable") costs a bit of polish.

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

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

For a read-only listing tool with no output schema and rich annotations, the description covers return shape, ordering, filtering, and a privacy boundary. The main omission is pagination semantics (how cursor/limit interact across pages), which the schema only partially carries.

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 80%, so the schema already documents role, since, cursor, and search. The description restates the three filter parameters without adding syntax or semantics beyond the schema, and says nothing about limit or cursor paging. 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?

The description gives a concrete resource and scope: base resumes plus tailored versions, sorted newest first, with named fields, score, and counts. It is clearly a listing tool distinct from get_resume, but it never names a sibling or states the exclusion explicitly, relying on the reader to infer the difference.

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?

"Filter by role, search or since" implies when the filters apply, but there is no statement of when to call this versus get_resume or list_templates, and no prerequisites or exclusions. Usage is implied rather than guided.

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 safety and determinism are covered. The description adds some value by disclosing the shape of the returned records (format, columns, suited roles, colour ids) in the absence of an output schema, though it says nothing about volume, ordering, or whether the template set is static.

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 short clause with zero filler, and the most important item (template ids) is front-loaded. The only cost is that the fragmentary phrasing lacks a verb, costing a sliver of readability without adding 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 zero-param, read-only, closed-world tool with no output schema, the description does the minimum useful work by enumerating return fields. It stops short of explaining what a 'format' or 'roles each suits' means for downstream use, leaving the agent to guess how to act on the results.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter information is missing or misleading.

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

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

The description names the resource (templates) and enumerates returned attributes (ids, format, columns, roles, colour ids), implying a listing operation. However, it is a bare noun phrase with no verb, so the agent must infer that this is a read/list action from the tool name alone. It is distinguishable from the resume-oriented siblings (create_resume, tailor_resume, etc.) only implicitly.

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?

There is no guidance on when to call this tool versus alternatives, and none of the resume siblings are referenced. The agent is left to infer that this is a discovery/lookup step, presumably before a create or tailor operation, without being told so.

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, idempotentHint=true and readOnlyHint=false, so the safety profile is carried. The description does add real context beyond them: the restore target is limited to changes made through this API. It omits whether the restore itself is recorded as a history action (and thus itself undoable).

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

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

A single dense sentence with no filler, and the core action is front-loaded. The trailing target-selection clause makes the sentence slightly harder to parse than necessary, but nothing is wasted.

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

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

For a two-parameter tool with full schema coverage and rich annotations, the description covers purpose, undo scope, and target selection. The one notable gap — how a restore interacts with the action history (does it append a new entry?) — is minor given the annotations already flag it as destructive and idempotent.

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%; both parameters are already documented, including 'the latest if omitted' on actionId. The description's 'the latest one, or the one named by actionId' restates rather than extends the schema. 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 ('Puts a resume back to how it was before a change') plus the scope restriction that only changes made through this API are restorable. The undo semantics distinguish it from update_resume and get_resume, though it never names those siblings.

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

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

Usage is implied by the phrasing 'put back to how it was before a change' — an agent can infer this is the undo path rather than update_resume. However, there is no explicit when-to-use/when-not, no mention of rollback vs. re-edit tradeoffs, and no reference to siblings.

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 goes beyond them by disclosing determinism ('One number, the same every time') and partial-read behavior ('Partial = not fully read'), which an agent needs to interpret results correctly. It stops short of saying what a partial result looks like or how matching is weighted.

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 short and front-loaded with the score and its range, but it is written as a telegraphic fragment chain rather than clear prose, and phrases like 'CVEmber' and 'how much its lines show' cost more comprehension than they save in length.

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

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

There is no output schema, and the description does supply the essential return shape ('One number' on a 0-100 scale) plus the determinism and partial-state caveats. What remains missing is how the sub-scores roll into the single number and what a partial result physically looks like.

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 67% schema coverage, the baseline is near 3. The description does add meaning for the optional job description ('how well it matches the job when one is given'), but the jobDescription parameter itself is undocumented in both schema and description, and no guidance is given on how keywords interact with resumeId.

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 identifies the resource (a resume) and the output (a 0-100 CVEmber score) and breaks the score into completeness/readability, job-match, and line-quality components. It never names a sibling such as get_resume or tailor_resume, so the differentiation from those is left implicit, and the phrase 'how much its lines show' is opaque jargon.

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?

There is no explicit statement of when to call this versus get_resume (raw content) or tailor_resume (rewriting). The only usage-adjacent signal, 'Partial = not fully read,' describes a result state rather than guiding tool selection or naming an alternative.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false; the description softens this with 'the master never changes' and adds meaningful invariants (no invented facts, no dropped content, versioning semantics). There is mild tension between destructiveHint=true and 'master never changes', but saving a new version is plausibly non-destructive to the master, so this reads as clarification rather than contradiction. What it never covers — what happens to the prior tailored version, storage limits, or failure/rollback behavior — is left unexplained.

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

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

Three sentences, front-loaded with the core action and its scoping rule before the content and questioning rules. Dense and mostly earned, though the run-on 'Wording the resume supports goes in; a new fact does not, nothing is dropped' is telegraphic enough to risk misparsing.

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 7-parameter, deeply nested write tool with no output schema and 57% schema coverage, the description covers the workflow but leaves key gaps: it references a questions[] array that does not appear in this schema without saying which sibling produces it, and it never indicates what a successful save returns (version id? confirmation?) for the caller to hand back.

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 57%, so the schema carries most of the load and the baseline is 3. The description does add genuine meaning for two params: the exact userStatedFacts shape ({questionId, text}) and the semantic rule for content (paraphrase only). It says nothing about resumeId, jobDescription, company, or targetTitle 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?

States a specific verb and resource — 'Saves a version for a job ad' — and immediately scopes it with 'the master never changes', which distinguishes it from update_resume (mutates master) and create_resume (new resume). It doesn't name those siblings explicitly, so an agent must infer the boundary, but the intent is legible.

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 real operating constraints: only wording the resume already supports goes in, no new facts, nothing dropped. It also prescribes the question-relay protocol (pass questions[] verbatim, never answer them yourself) and the answer channel (userStatedFacts). What's missing is an explicit statement of when to pick this over update_resume/score_resume.

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, idempotentHint=false and readOnlyHint=false; the description earns credit by adding that the edit saves a new version and that undo is restore_version, which the annotations do not convey. It does not explain whether omitting a section preserves or clears existing content — a meaningful gap for a destructive, non-idempotent mutation.

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-loaded with the action, then the concurrency contract, then the undo escape hatch. No filler; the only cost is the stale field names, which is a correctness issue rather than verbosity.

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 an 8-parameter, deeply nested, destructive mutation with no output schema, the description covers the version/undo story but leaves the most consequential semantics unstated: whether supplying sections replaces or merges existing sections, and what the returned version/state looks like. That is the minimum an agent needs before overwriting a resume.

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 63%, and the description does name the main writable targets and the optimistic-locking contract for expectedVersion. However it references 'changes' and 'questions[]', which do not exist in the schema (the actual field is userStatedFacts), so the parameter guidance is partly stale and potentially misleading rather than additive.

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 ('Applies the person's requested edit'), the resource (resume), and enumerates the mutable surface: sections, title, role, template, colour. It is clearly separable from create_resume (new resume) and restore_version (undo), which it names directly.

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

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

Gives a clear operating condition — expectedVersion must match contentVersion — and routes undo explicitly to restore_version, naming the alternative. It does not state when to prefer a different edit path (e.g. tailor_resume for tailoring) or what to do when the version check fails, so it falls short of full when/when-not coverage.

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