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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral detail beyond that: which domains are read in full, that a LinkedIn link is re-tracked on the company's own board, that status 'applied' is only valid once the person has applied, and that pasted text enables scoring. It stops short of auth/rate-limit context, so not 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?

Purpose is front-loaded in the first clause, followed by the url-vs-manual branch and then the sibling alternative. Dense but every sentence carries a decision the caller must make; minor tightening of the parenthetical examples is possible.

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 9-parameter tool with no required fields, an output schema, and full annotation coverage, the description supplies exactly the missing decision context: which input mode to pick, what status values mean, and the mark_job fallback for dedup. Return values and the timing parameters are covered by the output schema and 100%-described input schema.

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 cross-parameter conditional logic the schema does not: company and title 'may be left out' when url is a readable job link, and text substitutes when a link can't be read. It also clarifies the meaning of the default status value ('applied' only after the person applied), which is more than a restatement.

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 (add) and resource (an application/job jobwatch didn't find), and scopes it precisely as jobs the tracker missed (referrals, recruiters, LinkedIn). It also names the sibling it is not — mark_job — for jobs already tracked, 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?

Explicit when-to-use ('a job jobwatch didn't find'), when-not ('for a job jobwatch already tracks ... use mark_job instead'), and the conditional split between supplying a readable url versus company+title+text. Alternatives and preconditions are named rather than implied.

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?

Extraordinarily candid about side effects beyond the annotations: adding an existing entry only updates its name, the watchlist file is created if absent, the file is rewritten with a .bak copy kept, and hand-written comments are lost. The idempotentHint=true and destructiveHint=false annotations are consistent with these statements.

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 primary action and downstream consequence are front-loaded, and every sentence carries distinct information (prerequisite, idempotency, file creation, rewrite caveat). The prerequisite sentence is slightly dense but not wasteful.

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 needed for a file-mutation tool, the description still covers the mutation's side effects, idempotency, prerequisites, and data-loss caveat. An agent has everything needed to call this 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 both 'name' and 'entry' are already documented with format examples in the schema. The description references the source:board format via find_board/list_boards but adds no syntax detail beyond the schema, so the baseline of 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+resource ('Add a company's board to the watchlist') and immediately names the downstream effect (fetch_jobs checks it from now on), which distinguishes it from siblings like find_board and list_boards that only read boards.

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 prerequisites and workflow routing: find the entry with find_board first and verify sample titles, plus the warning that a guessed board name may belong to another company. It doesn't name when-not-to-use, but the sequencing guidance is concrete and actionable.

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 readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true; the description is consistent, explaining that state changes to postings are recorded (the write behavior implied by readOnlyHint=false). It adds the useful caveat that 'result' may be 'unknown' and must be re-checked manually, though it says nothing about permissions, rate limits, or how many postings are checked.

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, front-loaded with the action and ending with the operational rationale for running it first. The first sentence is dense ('postings of queued jobs and open applications still take applications, and record the ones that closed or came back'), slightly re-read worthy but not 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?

For a no-parameter, idempotent write tool with an output schema present, the description covers purpose, timing, and the meaning of the result field. Since an output schema exists it needn't enumerate return values further, though a note on whether it only inspects tracked postings would make it airtight.

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. The mention of 'result' values is closer to output semantics than parameter semantics, but does not hurt.

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 (check) and resource (postings), scopes it to queued jobs and open applications, and notes the side effect of recording closed/reopened postings. It also distinguishes itself from list_queued_jobs by positioning itself as a prerequisite step, so an agent can route correctly without reading 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?

Explicitly states when to run it ('before working through list_queued_jobs') and why (so time isn't spent on closed postings), naming the sibling tool it relates to. There is a clear ordering constraint rather than implied usage.

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 safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true), so the description's job is to add beyond that. It does: it discloses that failures on individual boards are skipped while the rest are still recorded, which is non-obvious partial-failure semantics an agent needs. It does not restate idempotency or say what 'counts' comprise, but the added failure behavior is genuinely useful.

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

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

Two sentences, both front-loaded: the action first, then the failure behavior and the sequencing instruction. No filler, no restatement of the 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?

An output schema exists, so the description needn't enumerate return values; mentioning that it returns counts is a helpful hint rather than a gap. Combined with the partial-failure note and the ordering against get_digest, an agent has everything required 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 tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description correctly avoids inventing inputs and instead explains behavior.

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 every board in the watchlist and record new roles'), scoping the action to the whole watchlist. It also names the complementary sibling get_digest, so an agent can distinguish it from the listing tools 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?

Explicitly tells the agent to run this before get_digest and explains the division of labor (this records; get_digest lists the roles). This is a clear sequencing rule, though it gives no explicit 'when not to use' condition or alternative for already-fetched 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/openWorld/non-destructive, so safety is covered. The description adds a genuine behavioral caveat not in the structured fields: a guessed name may match the wrong company, so sample titles should be checked first. That is useful domain insight, though auth/rate-limit context is absent.

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, front-loaded with the core action and scope, then the caveat, then routing. Every sentence earns its place with no 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?

An output schema exists so return format needn't be explained, annotations carry the safety profile, and the description supplies the pitfall caveat plus sibling routing. 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 100% and the single 'company' param is fully documented in the schema, so the description needn't carry parameter detail. It restates 'by name or by a job/careers link' but adds no syntax or format guidance beyond 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+resource: 'Find a company's job board by name or by a job/careers link.' It also names the resulting scope ('entries for the watchlist'), distinguishing it from siblings like list_boards and add_board without the agent needing to open 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?

Explicitly routes: 'Use it before add_board; to track one job from its link, use add_application instead.' This gives both the when (before adding) and named alternatives for adjacent intents.

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, so safety is covered. The description adds genuine behavioral context beyond that: the returned posting is a frozen snapshot ('as it read then'), which tells the agent this is not live data and that a file artifact (posting.md) exists. It does not describe the multi-match error path, though the schema does.

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, front-loaded with the payload contents followed by the routing guidance, with no filler. The first sentence is a dense list, but every element is load-bearing.

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 one well-documented parameter, no output schema, and full annotation coverage, the description supplies precisely what is missing: the shape of the return payload and the frozen-snapshot semantics. Nothing an agent needs to call 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 'key' parameter is documented in detail there (formats, fallback to company name, multi-match behavior). The description adds no parameter-level meaning, so the baseline 3 is appropriate.

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

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

The description enumerates exactly what the tool returns (files with their folder, form answers, note, the frozen posting.md) and frames it as the application package snapshot. It explicitly differentiates itself from get_interview_prep and get_job, so an agent can pick it 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?

'Use it to check exactly what was sent' states the positive trigger, and the two named alternatives each come with their own condition ('full prep sheet' -> get_interview_prep, 'posting and fit' -> get_job). This is explicit when/when-not/alternative routing.

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 safety profile (readOnlyHint=false, destructive=false, idempotent=false), and the description correctly implies mutation rather than contradicting it. It adds genuinely useful behavior beyond the annotations: the ranking logic and the stateful prerequisite that fetch_jobs must run first. It stops short of warning that the default call consumes/suppresses jobs (mark_shown=true) — that disclosure lives only in the parameter 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?

Three tight sentences, front-loaded with what the tool returns and its ordering, then the prerequisite, then the sibling routing. No filler and nothing buried.

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?

No output schema, so the description could say more about the shape of a digest entry (beyond 'people the user knows at each company'), and the default mark_shown=true side effect is not surfaced in prose. Still, prerequisite, ordering, and alternatives are all covered, which is most of what an agent needs.

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 the schema lacks: it explains why results come back 'best first' and ties fit score to the scoring pass that score_top controls. This makes the limit/score_top interaction legible without reading parameter docs.

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 scope: 'New jobs that pass the watchlist's filters, best first'. It also names the ordering rule (fit score, then keyword relevance), and explicitly distinguishes itself from list_queued_jobs and list_applications, so an agent can place it among siblings 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 an explicit prerequisite ('Call fetch_jobs first to pick up today's postings') plus a when-not/what-else routing: 'for jobs already queued use list_queued_jobs, and for applications use list_applications.' Both the trigger and the alternatives are stated.

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 non-destructive, so safety is covered. The description adds genuine context beyond that: resume lines are "quoted, never written" (no fabrication), the sheet output is markdown ready to read, and for hand-added applications the posting is resolved on a watched board by requisition id.

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 is front-loaded, but the middle is a dense, comma-spliced run-on ("what was sent, questions to expect and to ask, and the posting") and "markdown is the sheet ready to read" is awkwardly phrased. Every idea earns its place, but the packing hurts 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?

With no output schema, the description carries the return-value burden and does so by enumerating the sheet's sections and stating the markdown format. Key resolution and sibling alternatives are covered; only minor gaps remain (e.g., no indication of failure when no posting is found).

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 is one parameter with 100% schema coverage, and the schema already documents the key format, the bare-posting-id fallback, company-name matching, and the multi-match error behavior. The description only adds that a hand-added application resolves via requisition id on a watched board, which is marginal over 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?

The description names a concrete artifact (a prep sheet for a recruiter call or interview) and enumerates its contents: stage/next step, requirement-to-resume-line mapping, gaps, what was sent, questions, and the posting. It explicitly differentiates from siblings by stating that get_job and get_application_package give the raw pieces, so an agent can pick the right tool 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?

"Use it before a call" gives a clear trigger, and the closing sentence routes the agent to get_job and get_application_package when raw data is wanted instead. There is no explicit statement of when not to use it (e.g., no application yet), but the alternative routing is strong enough for a 4.

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, so safety is covered. The description adds real context beyond that: the candidate_home concept (the company's own sign-in page, Workday only, per-company account) and the breadth of returned data, plus the schema documents multi-match error behavior. It stops short of describing output format or size, so it earns 4 rather than 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-loaded with purpose, then the return inventory, then the routing sentence. The long middle enumeration is dense but each item is a distinct fact an agent needs to judge relevance; only minor trimming is possible.

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 carries the full burden of telling the agent what comes back, and it does so comprehensively — including the non-obvious candidate_home field. Combined with annotations covering the safety profile, nothing needed 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?

There is a single parameter and the schema description already covers it at 100% (composite key, bare posting id, or company name, with multi-match error behavior). The description only restates 'by key or posting id', adding no syntax beyond 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 retrieval verb and resource ('Everything about one job, by key or posting id') and then enumerates the payload: posting text, pay, tracking, fit score, referral people, skill gaps, application package, candidate_home. It is immediately distinguishable from get_application_package and get_interview_prep, 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?

Explicitly gives the use case ('tailor a resume or decide whether to apply') and routes to the right siblings with conditions ('for only what was sent use get_application_package, and for a call or interview use get_interview_prep'). 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 already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add context beyond that. It does: result ordering, the applied-or-later scope, and the meaning of a non-obvious field (candidate_home is the company's own status page, only present for some systems like Workday). That last point is genuine added value, though no pagination or volume behavior is disclosed.

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

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

Three dense clauses with no filler; the purpose and ordering lead, routing to siblings follows. The candidate_home clause is slightly tangential but earns its place by defining an otherwise opaque field.

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 read-only list tool with an output schema and full annotation coverage, this covers purpose, routing, ordering and one field's semantics. Little is missing; only the due_only behavior and result-size expectations go unaddressed, and the output schema absorbs most of that burden.

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

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

Schema coverage is 100% and the single parameter due_only is fully described there, so the schema does the heavy lifting. The description hints at follow-up timing but does not explain what due_only actually narrows the result to. 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?

States a specific resource ('every application ... and where it stands') with scope (applied or a later stage) and ordering (follow-ups due soonest first). It even disambiguates against the two nearest siblings, so an agent can distinguish it from list_queued_jobs and list_jobs 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?

Explicitly gives the trigger ('Use it to see what needs a follow-up') and names both alternatives with the condition that selects each: list_queued_jobs for not-yet-applied roles, list_jobs for any status. 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 already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so safety is covered. The description adds genuine behavioral context beyond that: what the listing contains and that the same watchlist is mutated by add_board/remove_board. It does not cover permissions or freshness of the watchlist file, so it stops short of 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?

Two sentences with no filler, and the resource being listed is front-loaded. The second sentence compresses three separate ideas (usage, alternative reads, mutating siblings) and the first is a verbless fragment, which costs it a point on polish but not on economy.

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 parameters, no output schema, and annotations already carrying the safety profile, the remaining burden is explaining what comes back and how it relates to siblings — which the description does. Minor omissions (whether the file path is user-specific, whether the list can be empty) keep 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?

The tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate. The description correctly does not invent parameter talk, though it also gives no hint about whether output ordering or scoping can be controlled.

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

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

The description names the specific resource (boards on the watchlist) and enumerates the returned fields (entry, display name, careers page) plus the watchlist file location. It explicitly distinguishes itself from siblings add_board/remove_board/fetch_jobs, so an agent can identify 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?

It states when to use it ('see what fetch_jobs checks') and names the alternatives that mutate the same data ('add_board and remove_board change it'). The when-to-use condition and the sibling routing are both explicit 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered; the description adds genuine behavioral context with 'newest first' ordering and the fact that closed postings are included, which is non-obvious for a job list. Pagination/limits are not addressed, but an output schema exists to carry return-shape details.

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, zero filler; the core behavior (untracked plain listing) is front-loaded before the disambiguation list. 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?

With annotations covering safety, a 100%-covered single enum parameter, an output schema handling return values, and clear sibling routing, 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 100% and the sole status parameter is fully described with its enum in the schema, so the baseline is 3. The description adds meaning by illustrating the filter's intent ('a plain list by status, e.g. every skipped job'), clarifying that it is an unranked equality filter rather than a relevance query.

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 ('tracked jobs'), plus scope qualifiers: newest-first ordering, inclusion of closed postings, and 'tracking fields'. It actively distinguishes itself from sibling list tools rather than restating the name.

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 three alternatives (get_digest, list_queued_jobs, list_applications) with the condition that selects each, and adds a plain-list use case ('every skipped job'). An agent can route without opening any schema.

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 behavior, so safety is covered. The description adds the sort order (oldest first) and actionable workflow context (ask contacts for a referral before applying, check warnings for pay/place/flagged text), which goes beyond the annotations. It stops short of describing volume limits or pagination.

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 purpose and ordering, then routing guidance. The parenthetical enumerations of fields and the referral aside add useful detail but make the single sentence dense; still, 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?

For a zero-argument list tool with an output schema, the description covers what an agent needs: what comes back, the sort order, how entries get here, and which sibling to use for other cases. Return-value detail is rightly left to the output schema.

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 per the rubric the baseline is 4. The description appropriately spends no space on argument syntax and instead documents what the (parameterless) result contains.

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 (queued jobs to apply to) and the ordering (oldest first), plus what each entry carries (fit scores, notes, contacts, warnings). It explicitly distinguishes itself from list_applications and marks mark_job as the source of these entries.

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 use case ('Use it to pick the next application'), how items arrive here ('through mark_job with status queued'), and names the alternative for the other case ('For applications already sent use list_applications'). 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 already establish readOnly/idempotent/non-destructive, so the bar is lower, and the description adds real value: it discloses the return shape (counts, on_resume flags, missing must-haves, fit-score gaps no course closes) and an agent-facing behavioral rule about not recommending unsupported skills. It does not cover pagination or result-size limits, which keeps it short of 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?

The opening is well front-loaded with what the tool returns, but the middle is a sprawling run-on with nested parentheticals enumerating output fields and every learning platform (Coursera, LinkedIn Learning, edX, nearby colleges). The detail is defensible given there is no output schema, but the structure is dense enough that an agent must parse several clauses to find the routing guidance.

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 carries the burden of describing the return payload and does so thoroughly, and read-only annotations cover the safety profile. What remains thin is the timeline parameter's behavior when omitted (it defers to the watchlist's learning.timeline without explaining the effect).

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 is a single optional parameter whose enum and default are fully documented in the schema (100% coverage), so the schema does the heavy lifting. The description only indirectly references it ('whether it fits the timeline') without adding format or defaulting behavior beyond what the schema already states; 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 precise verb+resource (list skill gaps across the person's matching jobs and applications) and immediately specifies the ordering ('most in demand first') and the per-skill payload (on_resume, job counts, missing must-haves, learning links). It explicitly separates itself from get_job and get_interview_prep, 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?

It states the scope (all matching jobs and applications, aggregated) and names two concrete alternatives with the condition that selects each: 'For one job's gaps use get_job; to prepare for a call use get_interview_prep.' It also states a hard usage constraint ('Recommend only from these links; never suggest claiming a skill the resume doesn't show').

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 the safety profile (destructive, idempotent, non-read-only), and the description adds operational behavior well beyond them: ambiguous key matches change nothing and return the offending keys in the error, empty strings clear fields, note replaces while add_note appends, and url/text are only for hand-added jobs. This is substantive disclosure of side effects and failure modes.

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 status list are front-loaded, and each subsequent clause maps to a distinct parameter or edge case, so little is wasted. It is dense and long, with mild redundancy against the schema's own field descriptions, which keeps it from a 5.

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 restated, and the description fills the remaining gaps: ambiguity handling, clearing semantics, append vs replace, and the boundary with add_application. An agent has everything needed to call this mutation correctly.

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

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

Schema coverage is 100%, so the schema already documents all nine parameters; the description largely mirrors those per-parameter blurbs. It still adds cross-parameter meaning the schema does not, notably the status-omission rule, the note vs add_note distinction, and queued meaning 'to apply to next'.

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 ('Record a job's status') and enumerates the full status vocabulary, making the operation unambiguous. It also explicitly contrasts itself with the sibling add_application for jobs not yet tracked, so an agent can distinguish the two 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?

It gives explicit when-to-use rules for the trickiest cases: 'applied only after the person has submitted the application themselves', 'omit status to keep it and only update the rest', 'prefer add_note for news', and 'For a job jobwatch doesn't track yet, use add_application'. Both the alternative tool and the selecting condition are named.

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 genuinely non-derivable behavior: previously recorded jobs/applications survive, the watchlist file is rewritten, and the old copy is preserved as .bak. That .bak detail is exactly the reassurance an agent needs before a destructive call. It lacks auth/prerequisite notes and error behavior, keeping it out of 5 territory.

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 and its effect, then the retention and backup guarantees. No filler and nothing repeated from 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 single-param destructive mutation with no output schema, the description covers what changes, what is preserved, and what is backed up. The remaining gap is only the return/confirmation behavior and failure modes, which are minor here.

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 `entry` parameter is fully documented in the schema with format and example ('greenhouse:stripe'). The description adds no further parameter detail, so the 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?

Specific verb+resource ('Take a board off the watchlist') with the downstream effect named ('so fetch_jobs stops checking it'). It is clearly the inverse of the sibling add_board, so an agent can distinguish them at a glance.

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 effect statement ('fetch_jobs stops checking it') implies when to reach for it versus add_board/fetch_jobs, and it clarifies the data-retention condition. It stops short of an explicit when-not (e.g., what to do if the entry is absent) or naming an alternative, but the context is unambiguous.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false. The description adds useful context beyond them: files are kept 'as copies' (not moved), and answers 'replace any saved before', clarifying partial-overwrite semantics. It does not cover auth or error behavior, but the added nuance is real.

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 a single dense sentence with parenthetical glosses for each parameter, front-loading the purpose before the usage instruction. The nested parentheses make it slightly awkward, but every clause carries 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 destructive save tool with no output schema, the description covers what is stored, when to call it, and how to read it back. It omits what the call returns (e.g. a confirmation or the saved key), which would round it out, but nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters well. The description largely restates the same parameter meanings ('exactly as uploaded', 'replaces any saved before'), adding little beyond what the schema already provides.

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

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

The description states a specific verb and resource: keeping copies of what was sent with an application (files, answers, note). It explicitly contrasts with the read counterpart, get_application_package, so an agent can distinguish it from its closest sibling 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?

It gives a clear timing condition ('Call it once the person has submitted, with what they actually sent') and names the read alternative ('get_application_package reads it back'). It does not spell out when not to call it (e.g. before submission is complete), but the context is strong.

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