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

Goes well beyond the annotations by disclosing that certain ATS links are parsed in full while LinkedIn is never fetched (robots.txt), that company/title may be omitted when a readable link is supplied, and that the reply ends with a duplicate warning that should be relayed to the user. This is exactly the operational behavior 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 the core purpose, but the long parenthetical enumerating ATS URL shapes duplicates the url parameter description and makes the prose dense and hard to scan. Some of that detail could be trimmed without losing routing value.

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

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

Given 9 optional params, an output schema, and annotations, the description covers the decision points (which source, which sibling, duplicate handling, LinkedIn limitation) an agent needs. Minor gap: it doesn't say what the returned warning or created application looks like, though the output schema likely handles that.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter dependencies the schema does not spell out: company and title are optional only when the URL is a readable job link, and text is needed otherwise so the posting can be scored. The link-format parentheticals largely restate the url schema.

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

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

States a specific verb and resource with scope: 'Add a job jobwatch didn't find (a referral, a recruiter, LinkedIn...)', and immediately contrasts with jobs jobwatch already tracks. An agent can distinguish this from mark_job and import_job_alerts from the description alone.

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: 'For a job jobwatch already tracks (it came from get_digest or get_job), use mark_job instead; for the jobs in job-alert emails, import_job_alerts.' It also clarifies the status semantics (applied only after the person applied). Alternatives and conditions are named, not 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?

Annotations cover the safety profile (idempotent, non-destructive), and the description adds substantial context beyond them: the watchlist file is rewritten, an old copy is kept as .bak, hand-written comments are lost, and the watchlist is created if absent. That is exactly the side-effect disclosure an agent needs before mutating a file.

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, and every following sentence carries a distinct rule or edge case. It is dense and slightly parenthetical-heavy, but no sentence is filler given the tool's real complexity.

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 3-parameter write tool with no output schema, it covers the full lifecycle: precondition lookup, dedupe behavior, the special-case parameter value, file-creation, and the destructive aspect of the rewrite. Nothing material to correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra by adding behavioral meaning to 'name' (leave it empty for Google because each role keeps its own employer) and by linking 'entry' to how find_board/list_boards present it. The 'careers' parameter is left to the schema alone.

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+consequence: 'Add a company's board to the watchlist, so fetch_jobs checks it from now on.' That downstream effect cleanly distinguishes it from read-side siblings like list_boards and find_board.

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 the agent: find the entry with find_board first and inspect sample titles, with a stated failure mode (a guessed board name can belong to another company) and a pointer to list_suggested_boards for alert/HN-sourced candidates. Duplicate handling and the Google no-name case are both 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?

Annotations declare openWorldHint=true, idempotentHint=true, and readOnlyHint=false, so the agent knows this touches an external system and mutates recorded state. The description adds real context beyond that: it records closed/reopened postings, returns open/closed/reopened/unknown, warns that 'unknown' must be checked manually, and notes an open job may be offline with a redirect. These details are not present in the annotations and materially help interpretation.

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 result, with the usage guidance placed last. It is dense and uses semicolons for clauses, which is slightly less scannable than ideal, but every sentence carries information and there is no filler.

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

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

With zero parameters, an output schema already present, and annotations covering the safety/network profile, the description supplies the remaining crucial context: what it does, which result values appear, and when to run it relative to list_queued_jobs. It is essentially complete for this tool's complexity, with only minor room to clarify the re-check behavior for 'unknown' 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 the description carries no parameter-semantics burden and the baseline of 4 applies. There is nothing malformed or misleading about the parameter story.

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

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

The description names a specific action on a specific resource: checking whether postings of queued jobs and open applications still accept applications, and recording closed/reopened ones. It also implicitly separates itself from list_queued_jobs by defining the validation role rather than the listing role. The verb 'check' is slightly generic, so it stops short of a 5.

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 sequencing guidance: 'Run it before working through list_queued_jobs, so time isn't spent on closed postings,' which tells the agent when this tool belongs in a workflow and names the sibling it precedes. It lacks an explicit when-not-to-use or a fully enumerated set of alternatives, so a 4 rather than 5.

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

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

Annotations already declare this as a non-read-only, non-destructive, idempotent write, so the safety profile is covered. The description adds a genuinely useful side-effect note ('Its jobs stay tracked'), clarifying that jobs are not removed when the suggestion is dismissed. It stops short of disclosing the response shape, though an output schema exists.

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 tight sentences, front-loading the core action and side effect before the routing hint. The trailing phrase 'with its add_board arguments' is slightly redundant and awkwardly worded, costing a point.

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, and annotations plus the schema carry the param and safety detail. The description completes the picture with routing and side-effect context; only the exact effect on the suggestion list versus the board itself is left implicit.

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% with a single required parameter, and the schema already spells out case-insensitivity, name-vs-board acceptance, and suffix handling. The description's reference to 'a company in list_suggested_boards' echoes rather than extends that. 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 verb ('Stop suggesting') and resource ('a company in list_suggested_boards'), tying the action directly to the sibling list whose results it affects. An agent can distinguish it from add_board, remove_board, and the other board 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?

Gives the triggering condition ('when the person doesn't want to watch it') and names the opposite-path alternative ('To watch one instead, use add_board'). The when-to-use and the when-to-use-something-else are both 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?

Annotations already cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=true), and the description adds genuine behavior beyond them: partial-failure semantics (failed boards are skipped while the rest are still recorded) and the meaning of the offline-board warning. This failure-mode disclosure is exactly the extra context annotations cannot carry.

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

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

Front-loaded with the core action and every clause carries information (counts, failures, warnings, sequencing). It is dense and parenthetical-heavy, which slightly hurts readability, 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?

Because an output schema exists, return values need not be spelled out, yet the description covers side effects, partial-failure handling, warning meaning, and the downstream call. Complete enough for an agent to invoke correctly; idempotency behavior could be made more explicit but is not essential.

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

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

The tool takes zero parameters, so the schema needs no supplementation and the baseline is 4. The description correctly avoids inventing parameter talk where none exists.

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 and scope: 'Check every board in the watchlist and record new roles.' It explicitly distinguishes itself from the sibling get_digest ('which lists the new roles themselves'), so an agent can separate the two without opening a schema.

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

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

Gives clear sequencing ('Run it before get_digest') and names the correct alternative for the offline-board warning case (add_board with careers). It does not state when not to run it, but the ordering and follow-up conditions are 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?

Annotations already declare this is a read-only, idempotent, open-world lookup, and the description adds substantial behavioral context: guessed names can belong to another company, sample titles should be checked, and several provider families require a job link rather than a name. These matching quirks go well beyond the annotations without contradicting them.

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

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

The description is long, but the density is justified by the many provider-specific lookup rules and examples. It is front-loaded with the core purpose and caution, though the provider details could be more scannable if structured as bullets.

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

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

With an output schema present, the description need not explain return values, and it covers the complex matching behaviors an agent needs before calling the tool. The annotations and schema are supplemented rather than repeated.

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

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

The schema documents the single company parameter at 100% coverage, but the description adds meaningful accepted forms and provider-specific syntax, such as avature:host/portal/careers, icims:<company>, jobvite:<company>, and hn:whoishiring. It tells the agent when a company name will work and when a link is required.

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: find a company's job board by name or job/careers link, and says it returns watchlist entries. It also distinguishes this lookup from add_board and add_application, so an agent can route correctly among 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?

It explicitly says to use this before add_board, and to use add_application instead when tracking one job from its link. It further gives concrete when-to-use-link guidance for Workday, Oracle Recruiting Cloud, Jibe, Avature, iCIMS, and Jobvite boards.

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 the safety profile is covered. The description adds useful context beyond that — that resolving duplicates is the person's call via mark_job, and that get_job surfaces duplicate_of for one job — but says little about ordering guarantees or output volume beyond the field list.

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 run-on paragraph mixing the definition, the strong/maybe distinction, output shape, and sibling references. Content is relevant but not front-loaded or structured, making it harder to parse than it needs to be.

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 spelled out, yet the description still sketches the per-pair payload (why, strong, both jobs with key/company/title/status/date/closed). Combined with the strong/maybe distinction and the mark_job handoff, an agent has what it needs to call this 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 baseline is 3, but the description meaningfully elaborates the single parameter by defining what 'strong' means (a shared req or posting id) versus 'same title alone', which is exactly what strong_only filters.

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 outcome: pairs of tracked jobs that are the same opening, with a distinction between 'strong' (shared req/posting id) and 'maybe' (same title) matches. It is distinguishable from siblings like get_job or check_postings, though it opens with a dense clause rather than a crisp verb+resource statement.

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

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

Usage is implied rather than spelled out: it notes 'the person decides what to skip (mark_job)' and that get_job's duplicate_of covers a single job, which hints at when to use this vs get_job. But there is no explicit when-to-use/when-not statement or prerequisites for invoking it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuine context beyond that: results are newest-application-first, sourced from save_application_package, and without a query the tool collapses to one row per distinct question with an 'asked' count. It says nothing about result caps or pagination, which is the only gap.

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

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

Front-loaded with what the tool returns before the routing advice, and every clause carries information. The semicolon-chained sentence is dense and takes a second pass to parse, 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?

With one optional parameter, an output schema, and rich annotations, the description covers provenance, ordering, dedupe behavior, and the sibling alternative. An agent has enough to call it correctly; only edge cases like result limits are unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds matching semantics beyond the schema: all query words must appear in the question, matching is case-insensitive, and the empty-query behavior returns one row per distinct question with its latest answer.

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: retrieves form answers the person gave on earlier applications, and enumerates the returned fields (key, company, title, applied, question, answer). It also explicitly distinguishes itself from get_application_package, which covers everything sent with a single application.

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

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

Gives an explicit when-to-use trigger ('before filling a form') with concrete examples of the questions to reuse ('reason for leaving', 'notice period', 'salary'), and routes the agent to the alternative sibling (get_application_package) for the other case.

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 cover read-only/idempotent/non-destructive, but the description adds substantive behavior beyond them: an error when nothing matches, name-matching against other companies, a 25-item cap with a more_open remainder, closed_unacted counting, and left_out_by filter attribution. These are exactly the edge cases an agent must anticipate before calling.

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

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

Purpose and routing are front-loaded in the first clause and the closing sentence, and nearly every fragment carries information. However, the middle is a dense telegraphic run-on ('left_out, with left_out_by: filter -> count', 'watch: ... and command') that is harder to parse than it needs to be.

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 and no nested objects, the description carries the full burden of explaining return shape and does so field by field (counts, jobs fields, contacts, watch/add_board, truncation buckets). Nothing an agent needs to call and interpret this tool is missing.

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

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

Schema coverage is 100%, so the schema already documents name and every_role. The description reinforces every_role's consequence (left_out/left_out_by appear unless every_role) but adds no syntax or format detail beyond the schema — 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?

Names a specific resource and scope: 'Everything tracked at one company' across all job statuses and open/closed, then enumerates the returned sections (counts, jobs, contacts, watch). It explicitly distinguishes itself from get_job, list_applications and list_jobs, so an agent can route correctly without opening a schema.

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

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

Gives an explicit trigger ('when the person names a company and you don't know which stage it's at') plus three named alternatives with their selecting conditions (get_job for one job's full text/fit/prep, list_applications for every application, list_jobs for one status). No inference is required.

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 read-only, idempotent, closed-world profile, and the description builds on that with real behavioral context: a 90-day freshness rule, a directive to report missing inputs rather than guess, and the semantics of the derived 'best' and 'suggestion' fields (weights, per-part scores, reasons). It duplicates a bit of the schema's default/precedence behavior, and never says how many items are compared or what the response looks like structurally.

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 lead clause is well front-loaded, but the body is a single sprawling run-on sentence whose long parenthetical chains (comp fields, ranking inputs) are hard to parse, and the crucial 'when to use' guidance is buried at the end.

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

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

With no output schema, the description must carry the return-value burden, and it does: it names the compared fields, the 'best' ranking basis, and the 'suggestion' breakdown including weights, sub-scores and reasons. What's missing is scale/limits (how many opportunities are included, whether nulls produce empty columns) for a tool whose output shape is otherwise undocumented.

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 each of keys/stages/companies already carries a precise description including the 'overrides stages' precedence, so the schema does the heavy lifting. The description adds no parameter-level detail beyond that (no format for keys, no cap on list size), so baseline 3 applies.

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

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

Opens with a specific verb and resource — 'Open applications side by side, to compare offers and processes' — then enumerates exactly what is compared (stage, applied day, next step, pay, fit score, contacts, comp, company health). It explicitly contrasts itself with list_applications, so an agent can separate it from sibling read tools 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?

States the triggering condition ('Use it when the person asks how their opportunities compare') and names the alternative for the adjacent case ('for one application's status use list_applications'). It also routes related writes to set_comp and set_company_health, and says to re-research health older than 90 days rather than reporting stale 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 declare non-read-only, open-world, non-idempotent, non-destructive; the description is consistent with these and adds substantive behavior beyond them: jobs left out stay new for the next digest, total counts matches before the limit, not_scored explains why a job is never scored, and the pace object's daily/max semantics. It does not state permissions or a return shape explicitly, but the behavioral context is strong.

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?

Information-dense and front-loaded with the return/ordering rule, then routing, then edge cases. Every clause carries weight, though the pace sentence is long and slightly buries the practical takeaway.

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, so the description must carry return semantics, and it does: total, not_scored, and pace are all explained. For a filtered, side-effecting digest tool with annotations covering the safety profile, this is nearly complete; only explicit auth/permission context 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 100%, so the schema already documents all four parameters, including defaults, the display.today rule for limit, and the per-job scoring cost for score_top. The description only gestures at the limit ('matched before the limit') and adds no parameter syntax beyond what the schema provides, 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?

States a specific verb+resource (a digest of new jobs that pass the watchlist's filters) and its ordering rule (fit score, then keyword relevance). It explicitly distinguishes itself from list_queued_jobs and list_applications, so an agent can route correctly without opening any schema.

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

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

Gives explicit when-to-use ('finding jobs to consider'), a prerequisite ('call fetch_jobs first to pick up today's postings'), and named alternatives for adjacent intents (list_queued_jobs, list_applications). It also encodes the pace rule, including the 'never refuse to help' guardrail.

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), and the description layers on substantial extra behavior: the private pay floor is deliberately never returned (pay.floor_withheld), resume lines are quoted and never written, invented story ids/numbers are stripped before return, and the model-backed modes send posting/resume/stories to Anthropic under the claude backend and are cached after a slow first call.

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

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

The purpose is front-loaded in the first sentence, but the body collapses into megasentences and fragment lists joined by colons and semicolons, making it taxing to parse. Nearly every clause carries information, so there is little true filler, but the structure is poor for an agent skimming for a decision.

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

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

With no output schema, the description must carry the return shape itself, and it does: it covers the sheet contents, brief, pay (posted/target/target_note), role_questions, drafted answers, practised answers, and story_gaps with the follow-up tool (save_story). A complex multi-mode tool is described completely enough to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by describing what each optional flag produces: draft_answers yields drafted/draft_note or an explanation for none, practised returns kept mock answers with an improved version, and role_questions falls back to generic expect questions when empty. It clarifies output semantics of the flags rather than just restating them.

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 opening clause states a specific verb+resource (a prep sheet for a recruiter call or interview) and then enumerates exactly what the sheet contains. It also explicitly distinguishes itself from siblings by noting that get_job and get_application_package give the raw pieces this tool assembles.

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; get_job and get_application_package give the raw pieces" gives a clear use moment and names the alternatives for a different need. It falls short of 5 because it never states when this tool is unnecessary or the prerequisite state of the job (e.g. applied vs queued), leaving some routing 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), but the description adds real behavior not visible there: the duplicate_of warning and its 'strong vs same-title-only' caveat, unscored_reason codes, link_note meaning that board pages are offline, and candidate_home being Workday-only with per-company accounts. That is genuine context beyond the annotations, though it reads more as return-field documentation than tool behavior.

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 leading clause is well front-loaded, but the remainder is one dense run-on of nested parentheticals with no paragraphing or list structure. The length is defensible because there is no output schema to carry the field semantics, but the wall-of-text delivery makes it hard to scan.

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 explaining what comes back, and it does so exhaustively: fit score, requirements verdicts, tracking fields, duplicate_of, unscored_reason, candidate_home. An agent knows exactly what to expect from a call.

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 'key' parameter is fully documented in the schema, including the source:board:posting-id format and the multi-match error behavior. The description only restates 'by key or posting id', adding no syntax or format detail beyond what the schema provides, 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?

Opens with a specific verb+resource+scope: 'Everything about one job, by key or posting id.' It then explicitly distinguishes itself from the two closest siblings (get_application_package for what was sent, get_interview_prep for a call or interview), so an agent can pick it apart without opening a schema.

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

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

Gives concrete when-to-use guidance ('Check it before drafting a referral request or an application. Use it to tailor a resume or decide whether to apply') and names the alternatives with their selecting conditions. 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?

Far exceeds what the annotations convey: it discloses that no mail password is needed, that tracking parameters are stripped, that robots.txt governs page reads (with the concrete LinkedIn/Indeed exception), the dedup rule ('jobs already tracked are left alone'), and where new jobs surface (get_digest, with 'via'). This is rich behavioral context consistent with the idempotentHint and non-destructive write profile.

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 and the trailing detail (robots.txt, results, alternative tool) is genuinely useful rather than filler. However, it is a dense run-on with heavy parenthetical nesting and no paragraph breaks, which hurts scannability.

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 burden of explaining returns and does so thoroughly (counts, plus key/result/how/filtered/duplicate_of per job) and covers the destination tool for further action (get_digest). Nothing an agent needs to invoke and interpret this tool 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 description coverage is 100%, so the three parameters (emails, dry_run, follow_links) are already well documented. The description reinforces the effect of follow_links ('Links lose their tracking parameters', board lookup behavior) but adds little parameter-level meaning beyond what the schema states, 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?

States a specific verb and resource ('Track the jobs in job-alert emails') and enumerates the sources supported (LinkedIn, Built In, Indeed, generic reader). It explicitly distinguishes itself from the sibling read_status_emails, which handles application emails, so an agent can route correctly without opening either schema.

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

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

Gives concrete when-to-use guidance with example mail search queries (from:jobalerts-noreply@linkedin.com, etc.) and instructs to pass each message in. It also names the alternative tool for a different email class ('For emails about the person's applications... use read_status_emails'), satisfying explicit when/when-not/alternatives.

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), yet the description adds real behavioral context: results sort follow-ups due soonest first, candidate_home only exists for some companies (Workday), and the 'move' field must never be changed by the agent ('never change it on your own'). That constraint materially changes agent behavior.

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

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

Front-loaded with purpose and routing, which is good, but the back half sprawls into an inline glossary of output fields (quiet, days, since, posting_open, long, move, advice, contacts) in a single run-on paragraph. An output schema exists, so some of that enumeration is redundant bulk.

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 tool with an output schema, the description is more than sufficient — it covers routing, sort order, and a behavioral constraint. It over-delivers by explaining return fields that the output schema already carries, which is waste rather than a gap.

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

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

Schema description coverage is 100% for the single due_only parameter, so the schema fully documents it and the baseline is 3. The description hints at the due-filtering concept ('follow-ups due soonest first') but adds no syntax or default detail beyond the schema.

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

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

States a specific verb+resource with scope: 'Every application (applied or a later stage) and where it stands.' It explicitly distinguishes itself from list_queued_jobs and list_jobs, so an agent can route without opening a schema.

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

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

Gives explicit when-to-use ('see what needs a follow-up') plus two named alternatives with their selection conditions: list_queued_jobs for not-yet-applied jobs, list_jobs for any status. Nothing 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 openWorldHint=false, so the safety profile is covered. The description adds value beyond them by disclosing the shape of what comes back (board entry, display name, careers, careers_link) and the fact that a watchlist file backs this data — information the annotations cannot convey.

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 that front-loads the core purpose, with the parenthetical field glossary and the alternative-tool note following. The nested parenthetical is slightly clunky, but every clause carries information and nothing is redundant.

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

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

With no output schema and no parameters, the description carries the return-value burden and does describe the notable fields plus the watchlist file location. It leaves ordering, count, or file-format details unspecified, but that is minor for a zero-argument read of a small local list.

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 of 4 applies. The schema is an empty object with full coverage, and no parameter-level detail is needed or missing.

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

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

States a specific verb and resource (list the boards on the watchlist) and then enumerates the returned fields — entry, display name, careers page, careers_link. It also explicitly separates itself from add_board, remove_board and fetch_jobs, so an agent can pick it without opening any other 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 see what fetch_jobs checks; add_board and remove_board change it" gives a clear use context and routes mutations to the sibling tools. It stops short of an explicit when-not or a statement of prerequisites, but the alternative is named and the selection condition is implied strongly.

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 and non-destructive, so safety is covered; the description adds ordering ('oldest first') and, more valuably, the meaning of the first warning and duplicate_of as a duplicate-opening signal. It does not mention pagination or limits on the queued list, so it stops short of full behavioral disclosure.

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

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

The key routing information is front-loaded and every sentence carries content, but it is a single dense paragraph mixing return-field inventory, referral workflow advice and sibling routing. Slightly sprawling for a no-argument list tool.

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

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

With an output schema present, the description need not enumerate return fields, yet it still supplies the interpretive semantics an agent needs (warnings, duplicate_of) plus routing to list_applications. Nothing an agent needs in order 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?

The tool takes zero parameters, so per the rubric the baseline is 4; the description correctly avoids inventing any argument semantics. Nothing further is required here.

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 concrete resource and scope ('Jobs queued to apply to, oldest first') and explicitly contrasts itself with list_applications for applications already sent. An agent can distinguish it from list_jobs and list_applications 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?

It states the decision context ('Use it to pick the next application'), how jobs arrive here ('jobs get here through mark_job with status queued'), and names the alternative for the other case ('For applications already sent use list_applications'). Both when-to-use and when-to-use-something-else are covered.

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

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

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?

This is where the description earns its keep: readOnlyHint=false would otherwise be confusing for a 'list' tool, and the text explains why by disclosing that look_up_boards makes web requests once per company and keeps what it finds, while rescan 'reads nothing from the web; safe to repeat.' That goes meaningfully beyond the annotation flags and identifies the network/persistence behavior.

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 one very long run-on paragraph with deeply nested parentheticals, and the essential action is not front-loaded — the first sentence mixes purpose, data sources, ranking logic, and caveats before the agent learns what the tool returns. It also spends much of its length re-describing return fields that the output schema already defines.

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

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

Given the complexity (multi-source suggestions plus a web-lookup side effect) and the presence of an output schema, the description supplies enough operational context to call it correctly and interpret results, including the board_found provenance and the pre-built add_board arguments. The only real gap is that result fields are re-explained rather than relying on 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?

Schema coverage is 100%, so the schema already carries limit, rescan, and look_up_boards semantics in detail; the description mostly defers back to it ('see its description'). The narrative adds context for why rescan exists (filters changed, or posts fetched before they were noted), but the baseline 3 applies when the schema does the heavy lifting.

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 name plus the opening enumeration of what each suggestion contains makes it clear this tool lists candidate companies to watch, and it names the relevant siblings (import_job_alerts, add_application, fetch_jobs, find_board, add_board, dismiss_suggested_board) so an agent can place it in the workflow. It never states the action in a clean verb+object form, but the resource and scope are unambiguous.

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 closing line 'Suggest; let the person decide which to add' and the routing to dismiss_suggested_board for removal, rescan for picking up previously kept HN posts, and find_board when no board was found give a clear sense of when to reach for this tool and what to do next. There is no explicit exclusion versus list_boards, but the sourcing condition (job-alert emails, add_application, watched HN threads) is a practical filter condition.

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

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

Annotations already flag this as a destructive, non-read-only, open-world mutation, but the description adds concrete effect semantics: 'note replaces the whole note', 'An empty string clears a field', the no-op-plus-listing error when key is ambiguous, and the side effect that supplying url/text enables scoring. It does not mention permissions, rate limits, or what the reply payload contains, 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?

The purpose and status list are front-loaded in the first clause, and nearly every clause carries a distinct rule, so the density is largely earned. The long semicolon-chained sentences and parentheticals make it harder to scan than it needs to be, and the closing 'tell the person' instruction is awkwardly grafted on.

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 mutation tool with an output schema, the description covers status semantics, all field behaviors, clearing rules, ambiguity/error handling, and the sibling alternative. Return values needn't be explained since an output schema exists, and 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%, so the baseline is 3, and the description does add real meaning beyond it: accepted key forms and ambiguity resolution, the 'empty string clears' convention, follow_up's +N format, applied_on defaulting to today, and the downstream consequence of url/text (posting read and scoreable). It is close to exhaustive but still leaves the note vs add_note precedence 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+resource ('Record a job's status') and enumerates the full status vocabulary, so the agent knows exactly what domain this mutates. It also explicitly distinguishes itself from the sibling add_application ('For a job jobwatch doesn't track yet, use add_application'), which is unusually strong sibling differentiation.

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

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

Gives explicit when-to-use and when-not rules: 'Use applied only after the person has submitted the application themselves', 'prefer it [add_note] for news', and the redirect to add_application for untracked jobs. It also covers an ambiguous case (queuing a duplicate opening still queues it and surfaces a warning), leaving little 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 a non-read-only, destructive, idempotent write, and the description adds value beyond them: the mutation is scoped to contact ordering/listing, the return payload is spelled out (name, company, position, verdict, note) despite no output schema, and the ambiguity error is disclosed. Minor gap: it does not say whether 'clear' also discards an existing note, which matters given destructiveHint=true.

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 verb and resource are front-loaded in the first clause and every sentence carries information (verdict meanings, trigger, scope, return, error). It is dense and parenthetical-heavy ('(a good person to ask for a referral: listed first wherever contacts are)'), which costs some readability but not correctness.

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 3-parameter tool with an enum and no output schema, the description covers trigger, effects, return shape, and the error case. The only real hole is what happens to an existing note when verdict is 'clear', which an agent could get wrong without a trial call.

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%, but the description still adds meaning: 'use' is explained as 'listed first wherever contacts are', 'clear' as returning to 'the usual order', and the note as 'shown with their name'. It also restates the who identifier and the name-disambiguation failure that the schema only hints at.

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 concrete verb+resource pair ('Record what the person says about someone they know at a company') and then enumerates the three verdict values and their effects. No sibling tool deals with contact ranking, and the phrase 'it only changes how contacts are ordered and listed' pins down the scope of effect precisely.

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?

'Call it when the person tells you whom to ask or not to ask' is an explicit trigger, and the note that it 'only changes how contacts are ordered and listed' bounds what the tool should be used for. The error path ('Errors when no connection (or more than one) has that name: then use their profile link') gives a concrete fallback, though no explicit when-not-to-call case is 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 cover the safety profile (read-only, idempotent, non-destructive, closed-world), and the description adds real behavioral detail beyond them: sidebars and footer are dropped from the parse, and an error is returned when no roles are found. That error-path disclosure is exactly the kind of context annotations cannot express.

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

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

Purpose and the field list are front-loaded, followed by the scoping constraint and error behavior. The dense run-on with parentheticals ('(Hybrid, Remote or On-site)', '(the description)') is slightly heavy but every clause carries information an agent needs.

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

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

A single required parameter with full schema documentation, an output schema covering the return shape, plus description-level disclosure of trimming, the no-network constraint, and the no-roles error. 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 schema's parameter description already specifies the source page and that a link is unacceptable, so the description need not compensate. It reinforces the source ('text of their LinkedIn experience page') and lists the parsed fields, but adds no format or syntax 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 and resource: extract roles (title, company, dates, location, bullets) from a person's LinkedIn experience page text, for interview prep. The follow-up sentence 'This only parses text it is given' resolves the misleading name 'read_profile' by making clear no external fetch occurs, distinguishing it from fetch-style siblings like fetch_jobs or check_postings.

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 clear operating context: use for interview prep on an interviewer or contact, and obtain the page text via the person's own browser because jobwatch never reads linkedin.com. It does not explicitly name a sibling alternative or state when-not to use it beyond the browser-sourcing constraint, so it falls short of a 5.

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

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

Annotations declare readOnly/idempotent/non-destructive, and the description adds genuinely new context: nothing is recorded, no mail password is needed, and statuses only move forward (a late confirmation for an already-interviewing application is not a proposal). It also discloses the return buckets, which the absent output schema does not.

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

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

Front-loaded with purpose and the core propose-don't-record behavior, and the dense parentheticals each carry real information (return buckets, kind examples). It is long, but the length is justified by the missing output schema; minor tightening 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 complex classification tool with no output schema, the description fully specifies the return structure (proposals, unmatched, nothing_new, other) plus the follow-up action, so an agent has everything needed to call it and act on the result.

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

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

Schema coverage is 100% and the schema already documents the single 'emails' parameter including accepted formats (RFC822, base64url, HTML/plain body). The description only adds the workflow instruction to search mail first and pass each message in, which is context rather than additional parameter semantics.

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

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

States a specific verb (read) and resource (emails about applications), and enumerates the email kinds it handles (confirmation, rejection, interview invite, offer, recruiter reply). It also names a sibling it is not (import_job_alerts) so the agent can disambiguate without opening schemas.

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

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

Gives an explicit workflow (search mail first, pass each message in), an explicit handoff condition (present proposals, only call mark_job for confirmed ones with the proposal's arguments), and an explicit exclusion (job-alert emails go to import_job_alerts). When/when-not/alternative 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?

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.

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

Annotations already declare a non-read-only, non-destructive, non-idempotent write, so the safety profile is carried structurally. The description adds genuine value beyond that: the concrete persistence target (stories: section or stories.yaml), the confirmation gate before saving, content-safety constraints (no internal system names, people, countries), and the return payload. It stops short of stating what happens on an overwrite or whether an existing story is replaced.

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 in the first clause, which is good, but the single dense paragraph bundles destination, workflow, content policy and return value, with semicolon-chained instructions that are easy to lose. Nearly every sentence earns its place, yet the packaging is heavier than the payload requires.

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 usefully discloses what comes back (the story as saved, the file, and the story count). Combined with the storage location and the confirmation requirement, an agent has enough to call it correctly; only the overwrite/collision behavior for an existing story is left implicit.

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 every parameter including id, did, hard, result, avoid and skills is already documented in the schema itself. The description's one added rule — only confirmed material goes in did/hard/result and the rest goes in avoid — is meaningful routing logic, but it largely restates what the avoid field description already says.

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 ('Add a story to the person's story file') and names the exact destination (the watchlist's stories: or stories.yaml beside it). It also scopes the content domain to drafted interview answers and mock interviews, which separates it cleanly from sibling tools like get_interview_prep and save_application_package.

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

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

Gives an explicit trigger ('Use it after interviewing the person about one of get_interview_prep's story_gaps') and names the upstream sibling that produces the gap list. It also states the interaction protocol (one question at a time, label typical details as common patterns, confirm before saving), so when-to-use and how-to-use are both answered.

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

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

Adds real behavioral detail beyond the annotations: partial-update semantics ("Only the fields given change"), the empty-string-clear rule that explains destructiveHint, and the parsing rule that the first amount found is read to mark the highest. It does not mention permissions or how ambiguous keys resolve, but that is covered in the 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?

Front-loaded with purpose, but the sentences are long and colloquial ("Keep what a recruiter told the person"), and the trailing "Returns what is kept for the job" is vague and arguably wasted. The core content is right, the phrasing is not tight.

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 10-parameter destructive write with 100% schema coverage, the description covers mutation semantics, clearing behavior and amount parsing. It is thin only on the return value (no output schema exists, so a one-line summary is acceptable) and on error handling, which the key parameter's schema already describes.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by stating the amount-format expectation ("Write amounts the way they were said, '165-195K'") and the 'first amount found' interpretation rule, which the schema doesn't spell out. It also flags that role and career_note are the career-value fields.

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: it stores what a recruiter said about pay for a job, plus career role/notes for that job. It names the sibling consumer (get_comps), which makes the read/write split clear. The only weakness is the folksy phrasing ("Keep what a recruiter told the person") that a non-native agent may parse slowly.

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 'what a recruiter told the person about pay' and by naming get_comps as the downstream reader, so the agent can infer this is the recording step. There is no explicit 'use when' trigger and no statement of when to prefer another tool (e.g. get_comps, get_job) or what to do if the job is unknown.

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 destructiveHint=true and idempotentHint=true, and the description explains exactly why: "Only the fields given change; an empty string clears one" — the precise destruction mechanism an agent must know. It also discloses the return shape ("Returns what is kept, with how old it is") and that no fetching happens server-side, context the annotations cannot convey.

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 consumer lead the sentence, followed by sourcing rules, then update semantics and return format — a sensible order with no filler. It is dense but each clause (sources, day, don't guess, empty clears) carries distinct instruction.

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 12-parameter mutation with no output schema, the description covers the essential unknowns: sourcing responsibility, staleness via the recorded day, clearing semantics, and what comes back. Only minor things (e.g., behavior on an unknown company) are left to the 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; the description still adds set-level semantics the schema does not: partial-update behavior, empty-string-as-clear, and the instruction to omit unknown fields rather than guess. That meaningfully changes how an agent populates the 12 optional fields.

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?

"Keep what is known of a company's health, per company, for get_comps to show and weigh" names the verb (record/keep), the resource (company health facts), the scope (per company), and the consumer (get_comps). This clearly separates it from siblings like set_comp (compensation) and get_company (read-side), so an agent can pick it without opening the schema.

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

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

Gives concrete operational guidance: "Search the web yourself (jobwatch fetches none of these sites)", supply source links and the day, and "say so when you could not find something, and leave that field out rather than guessing." It lacks an explicit contrast with set_comp/get_company, but the when-and-how is unambiguous.

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