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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context: results are scoped strictly to the authenticated user (no cross-user access), the page cap is 50 with a default of 20, and each result carries pagination info plus a summary of the underlying job search.

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 scope sentence followed by clearly labeled Input and Output blocks makes it quick to scan. The Input section largely duplicates the schema descriptions, which is mild waste, but nothing is significantly bloated.

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 three-optional-parameter read tool with annotations and an output schema present, the description covers scope, defaults, and output shape adequately. It leaves out what an alert payload contains in detail, but the output schema carries 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% and the description's Input block restates the same limit/offset/status text almost verbatim. The only value added is the 'default: all statuses' clarification for `status`, which the schema omits, so this sits just at the baseline.

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 ('Lists the authenticated user's job alerts') and scopes it precisely to 'all subscription sources (regular, company page, MCP)', which distinguishes it from the job_alert_subscribe/unsubscribe siblings that act on individual alerts.

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 only implied by the verb 'Lists' and the fact that the sibling tools are mutations. There is no explicit statement of when to prefer this over e.g. tracker_list or jobs_recommendations, and no exclusion guidance, so the agent must infer context.

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, but do not explain what is destroyed or how idempotency works. The description adds crucial context: it explains that active alerts can be changed rather than duplicated, details delivery modes and their constraints, describes digest vs fast email behavior, and clarifies the resulting email content. This goes well beyond what annotations provide.

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 structured with clear sections (Input, Output, Delivery) and uses bullet points. It is somewhat lengthy, particularly the Delivery section, but every part earns its place by explaining important behavior. It is well front-loaded with the core action.

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

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

Given the tool's complexity (idempotent updates, delivery options, email scheduling) and the presence of an output schema, the description is remarkably complete. It covers input validation, idempotency, conflict resolution, and delivery mechanics in detail, leaving no critical gaps for correct invocation.

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 parameters. The description adds some value by explaining the composite job ID format and the effect of unsupported fast delivery (validation error, keeping existing mode). However, it largely repeats schema details, so a 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+resource clearly: subscribes the authenticated user to alerts for a saved job search. Distinguishes itself from siblings like job_alert_list and job_alert_unsubscribe by focusing on creation/update of alerts. The idempotent-update semantics further differentiate it from any pure 'create' sibling.

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?

Description provides clear context for when to use it (subscribing to a saved search) and describes idempotent behavior on re-call, which implies repeated use is safe. However, it does not explicitly name alternative tools or provide when-not-to-use guidance, such as what to do if the user wants to unsubscribe or list alerts.

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

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

The description explicitly claims 'Idempotent: returns success even when the user was not subscribed or is already unsubscribed,' but the annotations declare idempotentHint=false. This is a direct contradiction of a declared behavioral trait, which is the most consequential kind of error for an agent deciding whether retries are safe.

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?

Roughly four sentences, front-loaded with the action, then clearly delimited Input/Output sections. The Input paragraph carries real information (accepted ID formats and their origin) rather than padding, and 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?

An output schema exists, so return values need not be explained, and the description still adds the ID-sourcing guidance and the idempotency/error behavior an agent needs. The only gap is the missing contrast with job_alert_unsubscribe_all, and the idempotency claim is contradicted rather than merely incomplete.

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 already 100%, so the baseline is 3; the description goes slightly beyond by naming the tools that produce the composite 'seo_id--job_search_id' value (jobs_search / jobs_details) and by restating requiredness, which helps an agent source the value correctly.

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 (unsubscribes), resource (job alerts), and scope (for a specific job search, by the authenticated user), which naturally distinguishes it from job_alert_unsubscribe_all and job_alert_subscribe. An agent can pick this tool over its siblings 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?

Usage is implied by the name and the 'specific job search' scoping, and the description helpfully says where the accepted ID format comes from (jobs_search / jobs_details). However, it never states when to prefer this over job_alert_unsubscribe_all, nor any prerequisites (e.g., auth/scope requirements) or exclusions.

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 real behavioral substance beyond them: the call is rejected unless confirm is true, and it returns success even when no alerts are active. It also states the output shape (a count of alerts unsubscribed). It restates idempotency that annotations already carry, which keeps it from 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?

Content is front-loaded with the core action in the first sentence and the guard/idempotency details after. The Input/Output headings are slightly heavy for a single-parameter tool, costing a little structure economy, but every sentence 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 one-parameter destructive bulk operation with an output schema and rich annotations, nothing an agent needs is missing: scope, the confirmation precondition, the rejection behavior, idempotency, and the return summary are all covered.

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 schema already documents that confirm must be true and that the call is rejected otherwise. The description adds only the rationale ('guards against an unintended bulk unsubscribe'), which is useful intent but no new syntax or format information. Baseline 3 is appropriate when the schema carries the 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?

The description opens with a specific verb and resource ('Unsubscribes ... from ALL of their job alerts') and scopes the operation precisely ('at once, across every subscription source (regular, company page, MCP)'). This cleanly distinguishes it from the sibling job_alert_unsubscribe, which handles a single alert, without the agent needing to open 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?

The 'ALL ... at once' framing makes the bulk-use case clear and implicitly routes single-alert requests to job_alert_unsubscribe, and the confirm guard establishes a precondition for execution. However, it never names the alternative tool explicitly or states when NOT to use this bulk operation, so it stops short of full when/when-not guidance.

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

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

Goes well beyond the annotations: it discloses that FoundRole validates evidence, stores the client extraction separately, derives missing deterministic facts, and reports whether each value was provided/derived/accepted/rejected/unknown. It also warns the analysis is a decision aid, not a guarantee on sponsorship, legitimacy, compensation, or hiring. Annotations (readOnlyHint=false, idempotentHint=false) are consistent with the described write-and-store behavior, though the description does not say what happens on validation rejection or whether repeated calls mutate state.

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

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

Front-loaded with purpose and the sibling routing in the first sentence, then input contract, then output/limits. It is dense but each paragraph carries distinct information. Minor deduction for some repetition of the null/omit rule that the schema already encodes.

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 16-parameter write operation with an output schema and annotations, the description covers input contract, validation behavior, and the key return value (comparisonRef retained for jobs_compare). It stops short of describing failure modes or rate limits, but the output schema covers return shape, so what remains missing is modest.

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 per-field baseline is 3; the description adds policy-level meaning beyond it — the five text identity fields are required, all structured facts are optional and should be omitted or null when the source is silent, and client_extraction labels must be evidence-backed. The evidence requirement and the provided/derived/rejected reporting semantics are the kind of guidance the schema alone cannot express.

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 ('Analyzes one job found outside FoundRole') and immediately scopes the work: it uses the authenticated user's profile and the same signals as native FoundRole jobs, enumerating them (resume match, missing skills, H-1B history, E-Verify, ghost-job risk, compensation, market salary). This is clearly distinguishable from jobs_details (native job lookup) and tracker_add_external (save).

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 away from the sibling: 'Use tracker_add_external only when the user asks to save without analysis,' which defines both when this tool applies and when the alternative applies. It also states the input assumption ('the direct posting URL and all job content already available in the conversation'), removing ambiguity about whether the tool fetches content itself.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds genuinely new behavioral context about the error mode (unanalyzed URLs fail because FoundRole has no posting facts) and about input fidelity requirements (preserve refs exactly, keep order, no duplicates). It does not describe how the comparison is rendered, but an output schema exists to carry that.

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 purpose sentence, then a second paragraph scoped entirely to the single parameter. Every sentence carries information, though the 'keep the user's requested order, do not send duplicates' clause is slightly bundled and could be tighter.

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?

Single-parameter, read-only tool with full schema coverage, an output schema, and closed-world annotation. The description covers purpose, valid inputs, prerequisites, and the main failure mode — nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% and the description still adds real meaning: it identifies the two distinct reference formats (exact FoundRole job IDs vs. exact external comparisonRef URLs), their provenance, the 2–4 cardinality, and the no-duplicate/order-preserving contract. That is substantially more than the schema's one-line item description conveys.

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 (compares jobs, 2–4 at a time) and enumerates the exact analysis dimensions produced, so the agent knows precisely what it gets back. It also implicitly separates itself from jobs_search and jobs_analyze_external by naming them as reference *producers* rather than comparison tools.

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

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

Gives a hard prerequisite: each external job must be analyzed by jobs_analyze_external first, because 'a bare URL that has not been analyzed cannot be compared.' It also states the source of valid refs (jobs_search, jobs_analyze_external) and ordering/dedup rules. It stops short of an explicit when-not-to-use or a direct comparison against a sibling tool like jobs_details.

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

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

The description adds real context beyond annotations: entitlement-dependent personalization of extended fields and the semantics of the conditional `remoteCheck` field. However, the annotations declare readOnlyHint=false and idempotentHint=false, which sits awkwardly with the purely 'fetches' framing and is never explained (e.g., that the call records analytics or consumes entitlement quotas) – a mild tension rather than a clear contradiction.

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

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

Front-loaded with the core purpose, then cleanly sectioned into Input and Output. Each line carries information the agent needs; the output enumeration is long but replaces the need to inspect the output 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 two-parameter read tool with full schema coverage, an output schema, and non-trivial annotations, the description covers purpose, input provenance, output shape, and conditional fields. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra by telling the agent exactly where each value comes from (`id` field of a jobs_search result, `resultItemId` when available), which the schema only states generically.

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 ('Fetches full details for one job by the `id`') and positions itself relative to a sibling ('the deeper view behind a search result' from jobs_search). An agent can separate it from jobs_search, jobs_compare, or jobs_recommendations 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?

Clear usage context: it must be invoked with an ID produced by jobs_search, optionally with the matching `resultItemId` occurrence. It does not state explicit exclusions (e.g., 'use jobs_compare instead when comparing multiple jobs'), 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?

The description discloses substantial behavior beyond the annotations: ranking, related roles, one-page/no-pagination behavior, default saved location, searchedPlace naming, and that a processing status means the feed is still being prepared. The remaining gap is that annotations mark readOnlyHint=false while the description frames this as a retrieval-style feed without explaining what non-read-only side effect or state change may occur.

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 front-loaded with the core purpose and then adds the important edge cases: query fallback, location default, one-page behavior, and processing status. It is somewhat long but most sentences earn their place; a few could be tightened without losing meaning.

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 19-parameter tool with an output schema and annotations, the description covers the key operational details an agent needs: personalization inputs, fallback to jobs_search, location default, no pagination, and asynchronous preparation status. It is largely complete, though it could say more about authentication or why the tool is not marked read-only.

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 carries the detailed parameter semantics. The description adds only a general note that the same search filters and sort parameters apply to this personalized feed, which is useful but does not add parameter-level meaning 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?

The description states a specific verb and resource — returns the authenticated user's personalized job recommendations — and explains the inputs that shape them: resume, skills, target roles, and preferred location. It distinguishes this personalized feed from the general search behavior used by jobs_search when an explicit query targets a different profession.

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 usage context and names the fallback relationship to jobs_search when the query targets a different or unrecognized profession. It also clarifies that search filters and sort parameters still apply, but it does not explicitly state the primary 'use this instead of jobs_search when...' rule for ordinary personalized browsing.

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?

Discloses behavior well beyond the annotations: saved-role preservation, searchedPlace/savedRole fields in every response, city-to-100-mile fallback and the posted_days_ago widening report, the possible guide question, remote-vs-hybrid independence, exclusion of jobs that don't state a filtered attribute, and entitlement-gated employer signals. None of this is recoverable from readOnlyHint/destructiveHint.

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?

Roughly 500 words of unstructured, run-on prose with no grouping of the 19 parameters. The final paragraph re-lists the advanced filters (sort, min_match, h1b_sponsors_only, salary_floor, remote, work_modes, benefits, bonuses_only, companies, exclude_companies) that were already explained individually, which is pure redundancy.

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

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

An output schema exists and annotations are present, yet the description still carries the genuinely non-obvious parts: personalization rules, fallback widening, and filter gating. Coverage is strong, though the tangle of overlapping rules (personalized feed vs general search vs saved role) is harder to apply than it needs to be, and the readOnlyHint=false annotation for a search is never addressed.

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 real semantic value: it maps user-stated constraints (remote-only, H1B, salary minimum, match grade) onto remote/h1b_sponsors_only/salary_floor/min_match, explains that unpassed constraints are silently not applied, that a shared company name covers all employers while a domain narrows to one, and that hiring_brand modifies company only.

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 ("Searches a database for real-time job listings") and immediately scopes it against siblings: roles_lookup for vocabulary resolution, jobs_details for full postings, jobs_recommendations for the personalized feed. 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?

Explicit routing rules: use roles_lookup when a word names no exact role, pass `id`/`resultItemId` to jobs_details, and use this tool's personalized path when a profile has a saved role. It also states the non-obvious operating constraints — one call returns one answer with no next page — 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 readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavioural context beyond that: empty groups are returned rather than padded with off-topic results, and results are nearest matches rather than an index of site coverage — both affect how an agent should interpret a thin or empty response. It loses a point for spending sentences enumerating returned fields that the output schema already specifies.

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 corpus, then facets, then exclusions — a logical order with no filler. The enumeration of article and page fields (title, url, summary, excerpt, date, tags) is redundant against the output schema and is the one stretch that does not earn 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?

Given a four-parameter tool with an output schema and full annotation coverage, the description leaves nothing an agent needs unresolved: corpus scope, facet semantics, empty-result behaviour, and sibling routing are all stated. Return-value structure is correctly left to the output schema.

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

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

Schema description coverage is 100%, so all four parameters are already documented, giving a baseline of 3. The description does add genuine meaning for the two facets — that `location` returns an analytical labour-market page rather than a list of openings, and that facets map to what the user is actually asking about — but most of that guidance is usage framing rather than per-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 and resource — semantic search over FoundRole's published content — and enumerates exactly what corpus it covers (blog articles, product/feature pages, industry landings, plus company and location facet groups). It is unambiguously separable from jobs_search and knowledge_topics, both of which it names.

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

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

Explicit when-not-to-use routing: jobs_search covers live roles and open-job counts, knowledge_topics covers overall topic coverage. It also gives a decision rule for the optional facets — 'a company mentioned only in passing does not need the company facet' — which is the kind of judgement an agent would otherwise have to guess.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description still adds value beyond them: no parameters, reflects the live published corpus, and summarizes the returned shape (counts, urls, totals). It doesn't discuss pagination or limits, but with zero params and an output schema those gaps are minor.

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 resource and scope, then the exclusion and sibling routing. Sentences are long but each carries distinct information — the only mild cost is that the payoff ('what it covers') arrives after a fairly dense clause.

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

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

For a zero-param read-only listing tool with an output schema and full annotation coverage, the description supplies everything an agent needs: what it returns, that it's live, and which sibling to use for article retrieval.

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?

Zero parameters, so the baseline is 4; the description correctly reinforces 'It takes no parameters,' removing any doubt that filtering is available. Nothing further is needed.

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

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

States a specific verb and resource ('lists what FoundRole's published career-guidance blog covers: every category and the most-used tags') and names the distinguishing scope — categories/tags plus counts, not articles. An agent can immediately tell it apart from knowledge_search.

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

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

Explicitly says it is 'the factual source for questions about the blog's topics or overall coverage' and names the exclusion plus the alternative: 'It does not retrieve articles for a specific question; knowledge_search does that.' That is the full when/when-not/alternative triad.

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 specific consequences beyond annotations: previous roles are removed, including a resume-derived role, and recommendations and title-less searches change accordingly. This is exactly the kind of destructive impact detail 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?

The purpose is front-loaded in the first sentence, followed by relevant destructive consequences and the sibling alternative. Every sentence conveys useful information with no redundant restatement of the tool name or title.

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

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

Given one parameter, 100% schema coverage, rich annotations, and an output schema, the description supplies the remaining behavioral context an agent needs: what gets removed, how recommendations change, and when to use the alternative tool. Nothing essential 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 parameter is already well documented in the schema, including where careerProfileId comes from. The description adds only a general reference to 'the one role the user chose' and does not meaningfully extend parameter semantics 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?

The description uses a specific verb and resource: it replaces the roles saved on the user's FoundRole account with one chosen role. It clearly distinguishes itself from the sibling profile_role_set by explaining that replace removes previous roles while set saves one for accounts with no role yet.

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 names the alternative profile_role_set and the condition that selects it: an account with no role yet. This gives the agent a clear when-to-use-this-vs-sibling rule.

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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), it discloses side effects the annotations cannot: a profile is created when none exists, recommendations and title-less searches are subsequently rewritten to that role, and on an account with another role it is a no-op that names the existing role. That no-op-plus-name return detail is exactly the kind of context annotations omit.

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 front-loaded with the action and scope, and most sentences carry distinct information. A few clauses are slightly redundant — 'a role the user names in the chat is saved the same way' partially restates the 'only a role the user chose' rule — but nothing is wasted enough to obscure the call.

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 write tool with annotations and an output schema, the description covers preconditions, side effects, idempotent behavior, return semantics, and the sibling alternative. There is no remaining ambiguity an agent would need to resolve before invoking it.

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

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

Schema coverage is 100% and the single parameter is already documented as careerProfileId from roles_lookup or a search question. The description still adds real meaning by constraining the value to a user-selected role rather than an inferred one, which is a semantic rule the schema does not encode.

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

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

The description opens with a specific verb+resource ('Saves the one role the user said they are looking for') and immediately scopes it to accounts with no role yet. It distinguishes itself from the sibling profile_role_replace by name, so an agent can separate the two without reading schemas.

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

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

It names both invocation contexts (the FoundRole search panel and a role named in chat), the precondition (account has no role yet), the explicit exclusion ('saves only a role the user chose, not a guess'), and the fallback behavior plus the alternative tool (profile_role_replace). This is close to a complete decision rule.

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, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond the annotations: the effect is clearing `reminderAt` on the tracked job rather than removing the job. It does not address what happens if no reminder exists, which matters given idempotentHint=false.

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 core sentence is front-loaded and clear, but the Input and Output blocks largely duplicate the input schema's parameter description and the output schema respectively. Those sections dilute rather than sharpen the definition, though the total length remains short.

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 required parameter, full schema coverage, an output schema, and annotations, the definition covers the essentials: what it does, which ID to supply, and the resulting state. The remaining gap is failure behavior (deleting a non-existent reminder) for a mutation flagged as non-idempotent.

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

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

Schema description coverage is 100% for the single parameter, so the schema already carries the semantics. The Input section of the description restates the schema text nearly verbatim, adding no syntax, format, or sourcing detail beyond what the schema provides; 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 opens with a specific verb+resource: 'Deletes a reminder from a tracked job,' which clearly separates it from sibling verbs like reminder_set or reminder_list without opening a schema. It does not, however, explicitly name an alternative or contrast itself with them, so it stops short of full 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?

There is no explicit when-to-use/when-not-to-use guidance or named alternative (e.g., reminder_set for replacing a reminder). The only guidance is implicit and ID-scoped: the description warns that `tracked_job_id` must come from `tracker_list` output and is distinct from `trackable.id` and `job.id`, which is a partial disambiguation guideline at best.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description usefully adds the sort order (soonest first) and that only jobs with *active* reminders appear, but says nothing about pagination, total counts, or how to page past the 50-result cap.

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 sentence is front-loaded and earns its place. The Input section duplicates the schema description word-for-word and the Output section restates what the output schema already covers, so roughly a third of the text is redundant padding.

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

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

For a read-only list with one optional, fully documented parameter and an existing output schema, the description is nearly sufficient — the agent needs no return-value detail. The remaining gap is routing guidance among the many sibling list/search/alert tools.

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 `limit` parameter is fully documented in the schema. The Input block merely restates it verbatim, adding no syntax, ordering, or default behavior 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?

States a specific verb and resource with scope ("Lists tracked jobs that have reminders set") plus an ordering guarantee (soonest first), which separates it from tracker_list and jobs_search. It stops short of naming a sibling to prefer or avoid, so it is clear but not fully differentiated.

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

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

There is no when-to-use or when-not-to-use guidance. With siblings like tracker_list and reminder_set/reminder_delete in the same namespace, the description never says which one to pick when an agent wants jobs versus reminders versus alerts.

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

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

The description adds useful behavioral detail beyond annotations by disclosing the confirmation email with .ics attachment and the returned updated tracked job. However, annotations declare destructiveHint=true and idempotentHint=false, and the description does not explain what may be overwritten/destroyed or how repeated calls behave. This is a gap, but not a contradiction.

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

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

The description is well-structured and front-loaded, with clear Input and Output sections. It is appropriately sized, though the Input section largely restates information already present in the schema, which is mildly 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?

For a simple two-parameter tool with a 100% covered schema and an output schema, the description provides enough context to invoke it correctly. It includes the key side effect and return value, though it could better address the destructive and non-idempotent behaviors signaled by annotations.

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 fully documents both parameters. The description mirrors the schema's parameter explanations, including the tracked job ID distinction and ISO 8601 future-date requirement, but adds no semantics beyond what is already structured. 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 states a specific verb and resource: it sets a reminder for a tracked job. This clearly distinguishes it from sibling tools such as reminder_list, reminder_delete, and tracker_update. It also scopes the operation to tracked jobs rather than general jobs.

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

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

Usage is implied by the purpose statement, and the description adds the constraint that remind_at must be in the future. However, it does not explicitly say when to use this versus reminder_list, reminder_delete, or tracker_update, nor does it mention exclusion scenarios.

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, and closed-world behavior. The description adds crucial context: deterministic parsing, return composition (readability band, biggest loss, additional findings, parsed facts, suggested fix), conditional saved report link, and explicit data retention caveats—far beyond what annotations provide.

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 well-organized into logical paragraphs, front-loading purpose and usage before return values and limitations. However, it is somewhat verbose for a single-parameter tool, with a long list of negations and a privacy caveat that could be tightened.

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?

Despite an output schema existing, the description provides a clear summary of return values. It also covers prerequisites, limitations, and privacy considerations, making it fully complete for an agent to call the tool correctly and interpret 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?

Schema coverage is 100% and the parameter is fully documented in the schema. The description adds modest value by contrasting 'plain text supplied in the conversation' with 'previously extracted text of the primary resume,' but the fallback behavior is largely already specified in the schema.

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

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

The description states a specific verb (checks) and resource (resume text) with precise scope: machine-readable sections, skills, contact channels, headline, and date ranges. It distinguishes itself from siblings (job alerts, searches, profile, etc.) by being the only resume readability tool.

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 states when to pass resume_text versus omit it, and clarifies what the tool is not (not an ATS test, hiring prediction, or layout check). It also lists operations it does not perform (upload, create, change, submit, fetch), leaving no ambiguity about boundaries.

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, and closed-world; the description adds genuinely new behavioral facts: result cap of 5, sort order (most jobs first), that counts are scoped to the place's state or country, that the saved role is appended, and that no job search is run. That is substantive context beyond the structured fields.

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

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

Compact and front-loaded: the core action and output come first, then the exclusion and the sibling pointer. Slightly awkward line wrapping and a somewhat overloaded second sentence keep it from a perfect score, but no sentence 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?

With an output schema present, the description need not explain return values, and it still covers scope, ordering, caps, and the side-effect profile. For a two-parameter lookup tool, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% and both parameters are documented in the schema, so the baseline applies. The description adds only a small amount — that 'location' drives an open-job count scoped to a state or country rather than a filter — and adds nothing about the 'words' free-text matching behavior (e.g., matching tolerance, max length).

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 ('matches the user's own words ... against FoundRole's role list') and describes the output shape (up to 5 roles, open-job counts, saved role included). It explicitly names the sibling it is not ('jobs_search returns the jobs for a role'), so an agent can route 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?

Clearly implies the trigger condition (user describes work in their own words) and explicitly excludes job search, pointing to jobs_search as the alternative. What's missing is an explicit 'use this when the user hasn't named a role yet' framing, but the routing is unambiguous in practice.

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 idempotentHint=true and destructiveHint=false, and the description reinforces this ('repeated saves return the existing tracked job'). More valuable is the non-obvious disclosure that a previously removed job is restored with its earlier status and notes — a side effect an agent could not infer from annotations. It stops short of covering auth or rate-limit behavior, so not a 5.

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

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

Purpose and the sibling routing rule are front-loaded in the first two sentences, which is the right ordering. The long sub_status enumeration duplicates the schema description nearly verbatim and inflates length, but the field list is otherwise tight and each remaining sentence (idempotency, restore behavior) 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?

With an output schema present, return values need not be explained, and the description still summarizes the return shape. Idempotency, restoration semantics, and the external-tool alternative are all covered, so an agent has enough to call it correctly; only the undocumented result_item_id parameter and lack of permission context leave a small 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 already 100%, so the baseline is 3, but the description adds the default value ('status defaults to "saved"') which the schema does not state, plus an enumeration of valid status values in one place. It omits the schema's result_item_id parameter entirely, keeping it from a 5.

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 (tracks/saves) and resource (a job from jobs_search results into the user's job tracker), with the identifying key (job_id) named up front. It explicitly differentiates itself from the sibling tracker_add_external, so an agent can route 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 an explicit when-to-use and when-not-to-use: jobs with a jobs_search job_id go here, while jobs found on the open web (URL, no job_id) must go to tracker_add_external. That is a concrete routing rule to the correct sibling, not just implied context.

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?

Goes beyond annotations by disclosing that a save never waits on facts the source omits, that FoundRole extractors derive missing salary/employment/education/skills, that client_extraction labels are validated and stored separately, and that repeated saves return the existing record (reinforcing idempotentHint). No auth or rate-limit context, but the mutation/extraction behavior is well covered.

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 two paragraphs are tight and front-loaded, but the extended field enumeration largely restates a schema that already has 100% description coverage, repeating enums verbatim. Structured well, yet noticeably longer than it needs to be for an agent that will read the schema anyway.

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 19-parameter mutation tool, the description covers required vs optional fields, the derivation/omission policy, the client_extraction evidence contract, and idempotent re-save behavior; return values are covered by the output schema. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning: status 'defaults to saved', the fact that non-source facts are simply omitted or null, and that the description field accepts a short summary. The bulk of the field list duplicates schema enums, so it does not reach the top of the scale.

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

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

States a specific verb and resource ('saves a job posting found anywhere on the open web into the user's tracker') with explicit scope, and directly names the sibling it is not (tracker_add, which takes a job_id). An agent can distinguish it from tracker_add 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?

Explicitly states when to use the alternative ('For jobs that came from jobs_search results, tracker_add ... is the right tool instead') and removes a common false prerequisite ('needs no prior jobs_search call'). Both the selection condition and the exclusion are spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that results come back grouped by status with pagination info, but nothing about empty results, ordering, or default sorting behavior — modest added value above the annotations rather than rich behavioral context.

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

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

The purpose line is front-loaded and the Input/Output sections are easy to scan. However, the Input block duplicates schema text that is already fully documented, so a portion of the content does not earn 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?

An output schema exists, so the description needn't detail return values, and the annotations cover safety. Combined with full schema coverage, the definition is nearly complete; only usage routing against sibling list/search tools 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% and the description repeats the three parameters nearly verbatim (including the same default/max notes). No extra semantics such as filter-combination behavior or what happens when status is omitted are provided, 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 and resource ('Lists the user's tracked jobs') plus the scope of optional filtering and pagination. The read-vs-mutate distinction from siblings like tracker_add and tracker_update_status is obvious, though it never explicitly distinguishes itself from adjacent read tools such as jobs_search or job_alert_list.

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

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

The description gives no when-to-use or when-not-to-use guidance and names no alternative, despite living among several similar listing/search tools (jobs_search, job_alert_list, reminder_list). The only steer is the implied 'optional' nature of the filters, which an agent must infer.

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, non-idempotent, non-read-only, so the safety profile is covered. The description adds only that the operation is confirmed on completion; it does not disclose whether removal is reversible, whether it requires the job to exist, or what happens on repeat calls — useful context given destructiveHint.

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 action, then cleanly sectioned into Input and Output. Slight redundancy: the Input block duplicates the schema description word-for-word, and the Output line restates what an output schema already conveys.

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 a single fully documented required parameter, an output schema, and annotations carrying the destructive/idempotency profile, little is missing. The gap is the absence of any note on reversibility or precondition behavior worth having for a destructive single-target operation.

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 description's Input block reproduces the schema text verbatim, so no meaning is added beyond the structured field. 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?

States a specific verb (removes) and resource (a job from the user's job tracker), and the intent is unambiguous against siblings like tracker_add, tracker_update, and tracker_list. An agent can distinguish the removal operation 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?

No statement of when to use this versus tracker_update or tracker_update_status, and no prerequisites or conditions. The only routing help is implicit — the ID distinction hints that tracker_list should be consulted first, but that is left to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is carried by structured data. The description adds modest value by listing the mutable fields and the reminder 'must be in the future, or empty to clear' rule, but it never addresses the key non-idempotent-update question: whether omitting a field preserves or clears it.

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 header/Input/Output structure front-loads the operation and the fields, and the required ID guidance comes first. It is somewhat verbose because it duplicates the schema field descriptions line for line, but nothing is incoherent or buried.

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

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

For a 7-parameter mutation tool with full schema coverage and an output schema, the description covers the required ID sourcing, the field set, and the one datetime constraint. The main remaining gap is partial-update semantics for omitted fields, which matters given idempotentHint=false.

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 every parameter is already documented in the schema, and the description largely restates those same descriptions verbatim. It adds no new syntax, format, or interaction 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?

States a specific verb+resource (updates a tracked job) and enumerates which fields can be changed, which implicitly separates it from tracker_update_status and tracker_remove. It never names those siblings explicitly, so the differentiation is inferable rather than stated.

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

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

It usefully tells the agent where the required ID comes from (tracker_list output) and warns it is distinct from trackable.id and job.id, which is real guidance. However, there is no explicit when-to-use vs tracker_update_status, nor any statement of when not to use this tool.

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

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

The annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered by structured data. The description does add one genuinely useful behavioral constraint — that sub_status is 'valid only for that status' — plus the fact that the updated tracked job is returned. It does not say whether the prior status is lost, whether the transition is reversible, or any auth requirements, but with rich annotations a 3 is appropriate.

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 one clean sentence, but the 'Input' section re-enumerates every parameter and its full enum value list, all of which already exist verbatim in the schema. That duplication roughly triples the length without adding information, which is padding rather than concision.

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 is not obligated to describe return values, and annotations carry the safety profile, so the core coverage is adequate. The missing piece is routing: for a status-mutation tool sitting beside tracker_update, the absence of any when-to-use guidance leaves the main decision an agent faces unresolved.

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 baseline is 3. The description restates the parameter list essentially verbatim from the schema, adding no syntax, format, or edge-case guidance beyond what is already structured — notably it does not explain what happens if a mismatched sub_status is supplied.

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 first sentence states a specific verb and resource ('Updates the status of a tracked job'), and the title adds the 'move to another stage' framing, which separates it from tracker_update. However, it never explicitly names tracker_update or explains what that sibling does differently, so the differentiation is left to inference.

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

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

There is no statement of when to use this tool versus the many siblings, most notably tracker_update and tracker_add. The description only lists inputs and outputs; an agent must guess whether status changes belong here or in tracker_update.

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