resumeai-mcp

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

With no annotations, the description carries the full burden and does so: it discloses server-side pacing (random 2-5 s delays, one tool at a time, never parallel), null semantics ('never guessed'), that logged_in=false is data not an error, and a bounded retry policy. This is unusually rich behavioral 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?

Purpose and the pre-work trigger are front-loaded, then return fields, then failure handling and pacing. Every clause carries information, though the single dense paragraph packs several distinct concerns (returns, auth failure, pacing, retry policy) that would scan better as separated lines.

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 auth/allowance gate with an output schema present, the description covers the return fields, the not-an-error case, the null cases, the prerequisite action on failure, concurrency constraints, and the retry matrix. 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?

The tool takes no parameters, so there is no schema semantics to add; the baseline for a zero-param tool is 4. The description correctly spends its words on outputs and behavior instead.

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 ('Check the Big Interview login and the remaining daily scan allowance') and clearly positions itself as a pre-flight check distinct from the scan-oriented siblings. An agent can tell immediately that this is the auth/allowance gate rather than a scan action.

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

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

Explicitly says to run it 'before starting any work' and prescribes the exact action when logged_in=false (stop and ask the user to run scripts/login.py). It also routes error handling via error.hint and names which error states must never be blindly retried.

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 full burden and delivers: feedback is locally backed up first and deletion aborts if backup fails (reversibility/safety), the server injects random 2-5 s delays and runs one tool at a time so tools must never be called in parallel, and a concrete retry policy distinguishes never-retry errors (auth_expired, site_changed, unknown_state, internal_error, profile_in_use) from transient ones bounded at two retries. This is unusually rich operational 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?

Purpose and the key anti-misuse warning are front-loaded, and every following sentence carries operational weight (backup, confirm, pacing, retry policy) rather than filler. It is dense with long parenthetical clauses, which costs a little readability, but nothing is expendable.

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. Given a destructive mutation with no annotations, the description supplies the missing safety profile, concurrency constraints, confirmation rule, and error recovery guidance — everything needed to invoke 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 description coverage is 0%, so the description must compensate. It explains confirm meaningfully (required when deleting the latest result of the current loop, defaulting false in the schema) rather than restating the boolean, though scan_id's format/derivation is left to the agent (contextually obvious from list_scans). Strong compensation with a small remaining gap.

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 ('Delete a scan from My Scans') and immediately scopes it against a tempting but wrong interpretation ('NOT a way to get more scans'). This distinguishes it cleanly from siblings like list_scans and start_scan, which an agent could otherwise conflate with scan management.

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 frames the tool as 'optional history tidying' and warns when NOT to use it ('never plan on allowance_restored'), then adds a precondition (confirm=true for the latest result of the current loop) and an error-handling policy keyed to specific codes. When-to-use, when-not, and what to do on failure are all 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?

With no annotations, the description carries the full burden and does so well: it discloses that partial=true means only badges were readable, that a local backup is written, that the server injects random 2-5 s delays and runs one tool at a time (never parallel), and how ok=false should be handled per error.hint with named non-retryable codes. This is far beyond what the schema 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?

Dense but front-loaded: content of the result comes first, then partial semantics, honesty rule, pacing, and error handling. Nearly every sentence carries operational information, though the honesty/pacing passages read as cross-tool boilerplate that lengthens the block.

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 tool with an output schema present, the description still explains the payload shape and adds the safety, pacing, and error-handling context an agent needs. Only the scan_id parameter and how to obtain it go unexplained, a small gap given the simple input.

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 should compensate, yet it never mentions scan_id. It is a single self-evident identifier whose intent is clear from the tool context, so the omission is minor rather than damaging, but it adds no semantic detail over 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+resource and enumerates exactly what the resource contains (medal, four badges, per-criterion status, action items, ATS keywords), which is precisely what distinguishes it from get_scan_status or list_scans. An agent knows it is the post-completion feedback reader, not a status poller.

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 (a 'completed scan', and partial=true for a truncated read), but the description never explicitly says when to call this versus get_scan_status, nor names an alternative. The rich error-retry guidance is about failure handling, not tool selection, so routing remains 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?

With no annotations, the description carries the full behavioral burden and does so richly: it distinguishes 'unknown' (unreadable, investigate, NOT a failure) from 'failed' (site reported failure), documents the server's 2-5 s randomized pacing and one-tool-at-a-time execution, and specifies retry limits and the ok=false/error.hint protocol. This is far beyond what the schema 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 the state enumeration an agent most needs, followed by polling cadence and error handling. It is a dense paragraph with no filler, though the pacing/retry material could be split or bulleted for faster scanning.

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-value detail isn't required, and the description still flags that scans_remaining is returned. Combined with the state semantics, timeout rule, retry policy, and the unknown-vs-failed distinction, an agent has everything needed to poll and branch 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?

Only scan_id is accepted and its schema description coverage is 0%, so the description must compensate. It implies scan_id identifies the scan being polled ('keep the scan_id') but gives no format, source, or validation detail. This is adequate but thin for the one parameter present.

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+resource ('Poll a scan's state') and enumerates the full set of possible states, so an agent knows exactly what this tool returns. It doesn't explicitly name or contrast against siblings like list_scans or get_scan_feedback, so the differentiation is inferred rather than stated.

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 concrete when-to-use rules: poll no more than once every 20 s, give up after 10 minutes, treat timeout as scan_timeout while keeping the scan_id, never call tools in parallel. It also spells out the error.hint routing (auth_expired, site_changed, unknown_state, internal_error, profile_in_use never retried blindly; otherwise at most two retries), which is actionable conditional 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?

With no annotations, the description carries the full burden and does so richly: it discloses server pacing (random 2-5s delays, one tool at a time, never call in parallel), pagination semantics (next_cursor null = last page), and error handling (follow error.hint; auth_expired/site_changed/unknown_state/internal_error/profile_in_use never retried blindly; else retry at most twice). This is exactly the behavioral context an agent needs.

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 parameters, then pacing and error rules; almost every clause earns its place. It is dense and slightly long, but there is no filler or repetition.

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

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

Output schema exists (so return shape is documented), and the description still covers pagination, pacing constraints, and the full error/retry policy. Nothing an agent needs to call this 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 0% and the schema gives no descriptions, so the description must compensate — and it does: limit range 1-50 with default 20, cursor should carry next_cursor from the previous response, and null cursor means the final page. It also explains the meaning of resume_sha256/jd_sha256 nullability.

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 (List), resource (past scans), ordering (newest first), and the two concrete purposes (reuse checks and deletion candidates). An agent can immediately tell this apart from start_scan, get_scan_status, delete_scan, etc. 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?

'for reuse checks and deletion candidates' implies when to use it, but no sibling is named as an alternative and no exclusion is given (e.g. when to prefer get_scan_status over listing). Usage context is implied rather than explicit.

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 the full burden and does: idempotency with reused=true and no quota consumption, the 5-daily-scan allowance, single in-flight constraint, server-side random 2-5 s delays, and per-error retry semantics. This is unusually complete behavioral disclosure for a mutation tool.

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?

Dense but well front-loaded: the core action and idempotency come first, then constraints, then polling and error guidance. Nearly every clause earns its place, though the error-policy sentence is packed tightly enough to be a little heavy.

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 mutation tool with no annotations and an output schema already present, the description still supplies what the schema cannot: quota, idempotency, concurrency, pacing, and the exact poll interval. 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 0%, so the description must compensate. It documents resume_path thoroughly (absolute path, text-based .pdf/.docx, max 5 MB) and ties job_description/job_title/company to the idempotency key, but it never explains what scoring_guide values are valid beyond the default. It covers the non-obvious parameters well and leaves only the self-evident ones implicit.

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 ('Upload a resume + job description and start a scan') and distinguishes itself from the polling sibling by naming get_scan_status explicitly. An agent can tell exactly what this does versus list_scans or get_scan_feedback.

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 routing: 'Then poll get_scan_status no more often than every 20 s', 'Only one scan may be in flight', 'limit_reached means stop for the day', and 'never call tools in parallel'. It also gives a concrete retry policy and lists which errors must not be retried blindly.

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