job-mcp

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

No annotations are provided, so the description carries the full disclosure burden. It does disclose the critical safety property — 'without submitting' and 'evaluate safety guardrails' — which counters the write-like name, and it says the application is 'staged' rather than committed. However it never says what happens when a guardrail fails, whether the staged preview expires, or what authorization is required.

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 non-submission guarantee is front-loaded in the first clause, which is exactly what an agent needs before anything else. The second sentence is slightly padded by the internal dispatcher name but remains short and scannable.

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. For a two-parameter preview tool with no annotations, the description covers intent, safety posture, and the required follow-up call; only failure-mode and auth behavior are unstated.

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 both `job_id` and the optional `cv_path` fallback are already documented in the schema. The description adds nothing about parameter meaning or precedence, 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: 'Inspect job application form and generate preview without submitting', which is far more precise than the tool name suggests. It also distinguishes itself from the confirmation sibling by framing itself as 'Step 1'. The 'Uses HybridApplicationDispatcher' sentence is an internal implementation detail that adds little for an agent.

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 positions the tool as the first step and names `confirm_auto_apply` as the follow-up path, which gives the agent a clear routing decision. It stops short of stating preconditions (e.g., must the job be bookmarked or match-verified first) or any when-not-to-use 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?

No annotations are provided, so the description carries the full behavioral burden. It implies a mutation but says nothing about idempotency (what happens if the job is already bookmarked), required auth/permissions, or whether the bookmark is reversible — significant omissions for a write operation with zero annotation coverage.

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

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

A single short sentence with the action and key front-loaded and no wasted words. It is efficient, though its brevity is partly the cause of the missing behavioral context rather than pure economy.

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

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

An output schema exists, so return values need not be explained, and the tool has only one simple parameter. Still, for an unannotated mutation whose behavior on duplicate bookmarks and permission requirements is unknown, the description is only minimally sufficient.

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

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

There is a single parameter with 100% schema description coverage, so the schema already explains job_id fully. The phrase 'by its ID' merely restates the parameter rather than adding format, source, or validity information, 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 (save/bookmark) and resource (job listing) plus the lookup key, so the action is unambiguous. However, it does not distinguish itself from close siblings like mark_job_as_applied or delete_job, which operate on the same job entities, so it falls 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?

The description gives no when-to-use guidance, no context about why an agent would bookmark versus apply to or delete a job, and no exclusions. With siblings like mark_job_as_applied and auto_apply_job in the same family, the absence of routing guidance is a real gap.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that the tool persists selectors into a dynamic registry and discovers alternatives heuristically, but it omits permissions, reversibility, side effects on the live page, and rate limits.

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 a clear one-sentence summary and then adds a concise elaboration. It is efficient, though the second sentence slightly restates the verbs from the first without introducing much new 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?

An output schema exists, so return values need not be explained, and the single parameter is fully covered by the schema. The description sufficiently explains the calibration workflow, though it could be strengthened with usage conditions or prerequisites.

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 parameter 'force_recalibrate' is fully documented in the schema. The description adds no further parameter meaning, 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?

The description uses specific verbs ('test, discover, calibrate') and a clear resource ('DOM selectors against the live page'), making the tool's function immediately distinguishable from the job-search/application siblings. It also states the core outcome ('persists verified selectors into the dynamic selector registry').

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 implies when the tool is relevant ('if layout changes have occurred') but does not explicitly state when to use it versus alternatives, nor does it provide exclusions or prerequisites. Usage is inferable from the described behavior rather than directly guided.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses that submission runs through HybridApplicationDispatcher and writes an immutable audit record in the ApplicationLedger, plus the ordering prerequisite. It does not state that submission is effectively irreversible, nor permission/auth or rate-limit considerations, which matter for a final write operation.

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 compact sentences with the action and prerequisite front-loaded; every sentence adds signal. The middle sentence about the dispatcher/ledger slightly elongates without changing the decision, keeping it just below a 5.

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

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

An output schema exists, so return values need not be explained, and the prerequisite is covered. However, for an irreversible write tool with no annotations, the description omits irreversibility, failure/duplicate behavior, and permission needs, leaving a meaningful 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%, so the meanings of force (bypass guardrails) and cv_path (override previewed CV) are already fully documented in the schema. The description adds only an implicit reference to job_id via the prerequisite, 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: it confirms and executes job application submission, and names the internal machinery (HybridApplicationDispatcher, ApplicationLedger). The 'Step 2' framing distinguishes it from the sibling auto_apply_job as the follow-up step in a pipeline. It stops short of a crisp one-line statement of what it does, but an agent can identify the operation.

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 an explicit prerequisite: auto_apply_job must have been called first for this job_id, which is exactly the routing condition the agent needs. It does not say when NOT to use it or mention the alternative (mark_job_as_applied) for already-applied jobs, so it falls short of a full 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?

No annotations exist, so the description carries the full burden. It says 'dismiss or hide from view,' implying a reversible view-level action, yet the name 'delete_job' implies permanent removal; the description never states which is true, whether data is destroyed, or whether the action can be undone. That destructive-vs-reversible ambiguity is the single most important behavior for the agent and it is left unresolved.

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

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

A single short sentence, front-loaded with the verb and resource, and free of padding. Its brevity is appropriate even though it leaves important behavior underspecified.

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 no explanation, but the description omits the crucial destructive-vs-reversible distinction and conflicts with the tool name. For a delete-named mutation with no annotations, this leaves an agent unable to safely decide whether to call it.

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

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

There is only one parameter (job_id) with 100% schema description coverage, so the schema already documents it fully. The description adds nothing beyond what the schema provides, which is the expected baseline when coverage is complete.

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 verb and resource ('Dismiss or hide a job listing'), but it conflicts with the tool name 'delete_job' and does not disambiguate whether the action is reversible. Sibling tools like bookmark_job and mark_job_as_applied are not distinguished, so an agent cannot confidently tell what this does relative to the family.

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 guidance, no exclusions, and no mention of alternatives such as bookmark_job for the same hiding/saving intent. The agent is left to infer when this tool applies.

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

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

With no annotations, the description carries the full burden. It usefully discloses that discovery is bounded and deterministic and that configuration is not persisted, which is real behavioral value. However, it omits auth requirements, rate-limit/network behavior, and what 'evidence' actually contains for a discovery operation.

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, front-loaded sentences with no filler. The core action leads, followed by return and non-persistence notes. Tight and skimmable, though the two trailing sentences could be folded together.

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

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

An output schema exists, so return-value explanation is unnecessary (and the description's return note is a harmless bonus). For a 3-param, zero-required, fully-documented tool, the description covers action, scope, and non-persistence adequately. The main gap is absent guidance on when to choose this over sibling discovery/job 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 coverage is 100%, so the schema already documents all three parameters (targets, career_url, company_name) with their constraints. The description only restates that inputs are company names or career URLs and adds no syntax, precedence, or interaction detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource: 'Identify supported ATS portals from company names or career URLs.' This is clearly distinguishable in substance from siblings like job_search or auto_apply_job, but the description never names or contrasts any sibling explicitly. Clear purpose, no 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?

The phrase 'bounded deterministic discovery' and the ability to accept company names or URLs implies the discovery use case, but there is no explicit when-to-use guidance, no prerequisites, and no named alternative among the many sibling tools. Usage is inferred rather than 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?

No annotations are provided, so the description carries the full burden. It says 'filter and rank' but doesn't disclose ranking behavior, whether it mutates cached state, what ranking criteria are prioritized, or how cv_path processing works. For an 8-param tool with no annotations, this is thin.

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

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

A single efficient sentence that front-loads the verb and resource, then the criteria. No wasted words.

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?

The output schema exists, so return values need not be explained. However, for an 8-param tool with no annotations, the description omits ranking behavior, cv_path processing mechanics, and the tool's relation to the broader job-search workflow — gaps that leave the agent guessing about invocation context.

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 parameter has a clear description, so the schema does the heavy lifting. The description lists the filter dimensions (tech stack, location, salary, CV) which mirrors the schema without adding syntax or format detail beyond it. 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 (Filter and rank) and resource (cached job listings) with the criteria it operates on. It distinguishes itself from siblings like search_linkedin_jobs or get_job_matches by specifying it works on already-cached listings, though the 'cached' aspect could be made more prominent.

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 guidance on when to use this vs. alternatives like get_job_matches or search_linkedin_jobs, nor any preconditions (e.g., must listings be cached first?). The agent is left to infer the tool's place in the workflow.

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

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

With no annotations, the description carries the full burden. It adds useful context by naming a 'persistent audit ledger' (durable, historical source) and 'Retrieve' implies a read, but it does not state ordering, pagination semantics beyond limit, or whether results are scoped to a user. Partial disclosure only.

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

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

A single front-loaded sentence with the verb, resource, and data source, and zero filler. Nothing could be trimmed 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 simple two-parameter read tool with a full schema and an output schema, the description covers what the tool returns and where the data comes from. The main gap is the absence of when-to-use routing against siblings, which keeps it from a 5.

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

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

Schema description coverage is 100%, so the schema already documents both 'limit' (default 50) and the optional 'status' filter with its allowed values. The description adds nothing about parameter syntax or behavior, 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 (retrieve) and a precise resource (historical job application submissions and outcomes), which is inherently distinct from the apply/search siblings. It stops short of explicitly differentiating itself from tools like mark_job_as_applied or search_linkedin_jobs, so it earns a 4 rather than 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?

There is no guidance on when to reach for this tool versus the many siblings that also touch applications, nor any stated prerequisites or exclusions. The purpose implies a reporting/audit use case, but the agent must infer it entirely.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: results come from cache unless stale or force_refresh=True, and cv_path triggers profile extraction that dynamically populates queries, seniority exclusions, and scores. It omits auth requirements, rate limits, and failure behavior, but the cache and dynamic-population semantics are real value beyond 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?

Three short sentences, each earning its place, with the core fetch purpose front-loaded before the cache and cv_path caveats. No filler or redundancy.

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

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

For a 12-parameter, zero-required tool with an output schema, the description covers the non-obvious behaviors (caching, force_refresh, cv_path-driven matching). It leaves out how matching/scoring is computed and any auth or rate-limit context, which keeps it short of fully complete.

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 semantics the schema does not: that sources defaults to all active registered sources and that cv_path causes automatic profile extraction that reshapes queries and scoring. These are behavioral couplings between parameters and results, not mere restatements.

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 ('Fetch') and resource ('matched job listings') and enumerates the registered sources, which clearly separates it from generic siblings like job_search or job_fetch. However, it never explicitly contrasts itself with those siblings, so the differentiation is implicit 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 implies usage through the cache/force_refresh and cv_path mechanics, but gives no explicit when-to-use guidance or exclusions against alternatives such as job_search, search_linkedin_jobs, or filter_jobs_by_preferences. The agent must infer when this tool is the right choice.

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

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

No annotations are provided, so the description carries the full burden. It states it retrieves details but does not disclose whether this is a read-only operation, authentication requirements, rate limits, or error behavior. The presence of an output schema reduces the need to describe return values, but key behavioral traits remain undisclosed.

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

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

A single, front-loaded sentence that is appropriately sized and contains no unnecessary 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?

The tool is simple with one parameter, and an output schema exists. The description is complete enough for an agent to understand what it does and how to call it, though it could mention that the job_id must be valid or that authentication is required.

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 the job_id parameter with examples. The description adds no additional meaning beyond what the schema provides, so the baseline of 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 clearly states a specific verb 'Retrieve' and resource 'full job details for a specific LinkedIn job posting', distinguishing it from search-oriented siblings like search_linkedin_jobs. It is clear but does not explicitly mention which sibling to use when only a summary is needed.

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: use when you have a specific job ID and need full details. However, there is no explicit guidance on when to use this versus search_linkedin_jobs or other retrieval tools, leaving some inference to the agent.

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

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

No annotations are provided, so the description carries the burden. It discloses that only factual retrieval status is returned, which is useful, and that 'ref' is opaque and versioned. However, it does not mention permissions, error behavior, or whether the result includes full job data or just status, leaving gaps for a retrieval tool.

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

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

Two short sentences, front-loaded with the core action and followed by the return caveat. No wasted words.

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 required parameter, an output schema exists (so return values need not be described), and the description covers purpose, source of input, and return nature. It is nearly complete, missing only minor behavioral details like error handling or authentication, which are not critical 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 schema describes 'ref' as an opaque, versioned JobRef string with an example. The description adds no parameter meaning beyond what the schema provides, 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?

States a specific verb (Fetch) and resource (one canonical job) with scope (single, by ref). It explicitly differentiates from job_search by naming the sibling and clarifying that this retrieves one job using a ref that job_search returns.

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 context: use after job_search to retrieve a specific job. It identifies the prerequisite (ref from job_search) but does not state exclusions or alternatives for fetching job details (e.g., get_linkedin_job_details), leaving some ambiguity about when to use another 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?

With no annotations, the description carries the full behavioral burden; it does disclose that results are opaque refs consumed by job_fetch and that searching spans all enabled sources. It is silent on read-only nature, rate limits, and the fact that cursor/seniority/freshness_days are rejected, which the schema alone must 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?

Three short, front-loaded sentences with no filler; the core action comes first and the ref/job_fetch contract follows immediately.

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

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

An output schema exists, so return-value detail is not required, and the description covers purpose plus the job_fetch handoff. For a ten-parameter tool it is nearly complete, missing only a note on the disabled/deferred filters and alternating-source selection.

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 ten parameters (including the deferred, rejected ones). The description adds no parameter-level meaning beyond that, 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 ('Search normalized jobs across enabled TechJobMCP sources') and clarifies the return contract (opaque refs). It implies the distinction from search_linkedin_jobs via 'across enabled sources' but never names the sibling or states the differentiator explicitly.

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?

'Provider knowledge is not required' tells the agent it can call this without knowing source families, which is useful implied guidance, and naming job_fetch gives a workflow hint. However, there is no explicit when-to-use versus search_linkedin_jobs / get_job_matches, and no 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?

No annotations are provided, so the description carries the full disclosure burden. It does usefully signal that this path does not touch the aggregator, provider health, browser, or model, implying a lightweight read with no provider side effects, but it never explicitly states read-only semantics, auth needs, or whether the lifespan run has side effects.

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 with the core scope ('configured source metadata only, not observed provider health') front-loaded. The final sentence about MCP transport lifespan is somewhat internal and only marginally helpful, but overall it is tight and readable.

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

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

For a zero-parameter listing tool with an output schema that already documents return values, the description supplies adequate purpose and scope. The main omission is any routing between this and the sibling source/job listing 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?

The tool takes zero parameters, so there is nothing for the description to document. Baseline 4 applies; no parameter-level ambiguity 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 and resource: returning configured source metadata. It also scopes the result by excluding observed provider health, which is genuinely clarifying. However, it never names list_job_sources or any sibling, so an agent cannot tell how this differs from the other source-listing 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?

There is no statement of when to use this tool versus alternatives such as list_job_sources. The notes about the aggregator, health, browser, and lifespan read as implementation detail rather than selection guidance, leaving the agent to infer usage.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that the response includes capabilities and health status, but says nothing about whether this is a safe read, whether it requires authentication, how health is determined, or whether results are paginated.

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

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

A single front-loaded sentence that names the resource first and the returned content second. No padding or redundancy, though it is arguably too terse given the missing usage and behavioral context.

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 need not explain return values, and the single optional parameter is fully covered by the schema. What is missing is the usage context that would let an agent choose this tool over list_configured_sources or job_search.

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 optional 'category' parameter is fully documented with its allowed values in the schema, so the baseline is 3. The description adds nothing about filtering behavior beyond what the schema already states.

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

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

States a specific verb (list) and resource (job sources) plus the scope of what is returned: capabilities and health status. However, it does not distinguish itself from the similarly named sibling list_configured_sources, leaving the agent to guess which listing tool applies.

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 guidance, no prerequisites, and never names an alternative. With list_configured_sources in the sibling set, the absence of any routing hint is a real gap.

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

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

With no annotations, the description carries the full burden, and it does disclose the important consequences: a durable ledger entry, cache dismissal, and permanent exclusion from future job scout runs. That is genuine side-effect disclosure beyond the schema. It omits idempotency behavior (what happens if called twice) and any permission requirements, 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?

Two short sentences, zero filler, and the core action is front-loaded with the durability consequence immediately after. Nothing is redundant with 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?

An output schema exists, so return values need not be explained, and the input schema fully documents parameters. The description supplies purpose and the key persistence/exclusion semantics, leaving only minor gaps (idempotency, auth expectations) for a mutation tool with no 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 all four parameters (including the notes example and job_id format) are already documented in the schema. The description adds no parameter-level meaning such as what job_id formats are accepted or how company/job_title are used in the record, 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 (record a job as applied) plus the mechanism (persistent ledger) and side effect (dismiss from cache). The word 'manually' cleanly distinguishes it from the sibling auto_apply_job, so an agent can choose between them 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?

The 'manually' framing implies this is the fallback when an application happened outside the agent (e.g., company portal), which is useful routing context. However, it never explicitly states when to use this instead of auto_apply_job or confirm_auto_apply, and offers no exclusions or preconditions, leaving the alternative choice 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?

With no annotations, the description carries the full burden. It usefully discloses the stateful dedup behavior (filter unseen via JobTracker, dispatch alerts), but for a tool with external side effects it omits that alerts are actually sent to a channel, that auto_mark_seen mutates tracker state by default, and any permission or rate-limit considerations.

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

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

A single twelve-word sentence ordered along the execution pipeline (scan, filter, dispatch) with no filler. It is efficiently front-loaded, though its extreme brevity leaves substantive gaps for a ten-parameter, side-effecting 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?

An output schema exists so return values need not be explained, but with ten parameters, zero annotations, and real side effects (outbound alerts plus tracker mutation), a one-line description leaves the agent without guidance on invocation context or consequences. It should do more given the tool's complexity.

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 ten parameters are already self-documenting, including defaults for channel, force_refresh, and auto_mark_seen. The description adds no syntax or semantics beyond what the schema provides, which is the baseline 3 case.

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 specific verbs and a clear three-step pipeline (scan aggregated jobs, filter unseen via JobTracker, dispatch alerts), so the agent knows this is the end-to-end notification flow rather than a search primitive. It does not, however, distinguish itself from closely related siblings like run_job_scout, test_notifier, or get_job_matches.

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 alternatives, nor any prerequisites or exclusions. The presence of siblings such as test_notifier (clearly a dry-run variant) makes the missing distinction especially costly, since nothing tells the agent to prefer one over the other.

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

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

With no annotations, the description carries the full burden and does disclose the significant side effects: automatic bookmarking and staged/submitted applications via HybridApplicationDispatcher, gated on auto_apply. It omits permission requirements, rate limits, runtime/latency, and any reversibility caveats for submitted applications, which matters for a mutating pipeline.

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 a single-sentence purpose, followed by one dense sentence enumerating the pipeline stages. Efficient, though the second sentence is a long run-on that could be split for scanability.

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 ('structured tracking metrics') need not be expanded, and all 20 params are schema-documented. The remaining gap is the absence of usage routing and safety/permission context for a 20-param tool that can submit real applications.

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 20 parameters are already documented in the schema. The description adds only a marginal cross-reference between action_mode 'autonomous' and auto_apply; it provides no syntax or default semantics beyond what the schema states, 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 ('Execute') and resource ('multi-source job scouting pipeline') and then enumerates the actual stages (discover sources, aggregate listings, score CV match, bookmark, stage/submit applications). This distinguishes it from granular siblings like job_search, auto_apply_job, and get_job_matches, which each cover only one stage.

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 explains what the pipeline does but never says when to choose it over the many sibling tools (job_search, auto_apply_job, get_job_matches, filter_jobs_by_preferences). There is no explicit when/when-not guidance or named alternative, leaving selection to inference from the enumerated steps.

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

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

No annotations are provided, so the description carries the full behavioral burden. The phrase 'guest seeMoreJobPostings endpoint' weakly implies an unauthenticated, read-only lookup, but the description says nothing about rate limits, pagination behavior, default location scoping ('Israel'), or what happens when keywords are empty and cv_path drives the query.

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

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

A single front-loaded sentence with no filler; the core action and endpoint are stated immediately. Nothing could be trimmed without losing content.

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 11 parameters and an output schema present, the schema carries most of the load, but for a default-scoped search tool with no annotations and many competing siblings, the description should at minimum explain scope, defaults, and how it differs from the other job-listing 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%, so the baseline is 3 and the schema already documents all 11 parameters, including enum-like codes for f_E, f_WT, f_TPR and sort_by. The description adds nothing beyond the schema and does not explain how overlapping filters (work_mode vs f_WT, keywords vs cv_path) interact.

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 verb and resource ('Search LinkedIn jobs') and even the underlying endpoint, so an agent knows exactly what the tool does. It does not, however, distinguish itself from look-alike siblings such as job_search, job_fetch, or get_job_matches, leaving the agent to infer the boundary.

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 search-adjacent siblings (job_search, job_fetch, filter_jobs_by_preferences, get_job_matches). No prerequisites, no when-not-to-use, no routing guidance at all.

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

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

With no annotations, the description carries full burden and does well: it explains the concrete behavioral consequence of autonomous mode (tool chaining without per-tool confirmation) and the important exception that confirm_auto_apply still requires explicit user confirmation. This is meaningful state-changing context. It does not, however, state whether the mode persists across sessions, who may set it, or whether the change is reversible.

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 statement of purpose followed by a concise consequence clause. Two short paragraphs, each earning its place. No redundancy.

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

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

Given one required enum-like parameter and an output schema that presumably returns the resulting mode, the description covers the essential behavior an agent needs. Missing only persistence/permission details and any rollback semantics. Sufficient 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% and the schema documents the mode parameter with its two allowed values. The description adds conceptual meaning ('supervised' vs 'autonomous' with behavioral effects) but no format or syntax detail beyond the schema. 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 (switch operation modes) and enumerates the two modes. Does not name any sibling tool to differentiate from, but no sibling performs the same function, so confusion risk is low. Clear but without explicit 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?

Implies when the switch matters by explaining what autonomous mode enables, but gives no explicit rule for when to call this tool vs simply proceeding. The conditional nature of the tool's effect is described, not its invocation 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?

No annotations are provided, so the description carries the full burden. It does disclose the key side effect (an actual alert message is dispatched) and a read-only-style health check, but says nothing about required channel configuration, permissions, or whether the test message reaches a real external destination.

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

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

A single front-loaded sentence with no filler. Minor redundancy between 'verify connectivity' and 'health check', which describe nearly the same activity.

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

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

Output schema exists, so return values need no explanation, and the single optional parameter is fully schema-documented. For a simple one-parameter diagnostic tool the description is nearly sufficient, missing only explicit guidance on when to run it and whether the test alert is externally visible.

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

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

Only one parameter with 100% schema description coverage, so the schema already documents 'channel' and its 'telegram' default. The description adds nothing about valid channels or how the default is chosen, 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?

States specific verbs and resource: 'Verify notifier connectivity, health check, and dispatch a test alert message.' An agent can tell this is a diagnostic/test tool rather than the production notifier, though it never names the sibling notify_new_jobs it should be contrasted with.

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 words 'test' and 'health check' – an agent can infer this is a pre-flight/diagnostic call, but the description gives no explicit when-to-use, when-not, or alternative (e.g. 'run this before enabling notifications').

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