Refine Job Search

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

The annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds only the notion of an 'upcoming' window; it says nothing about how far ahead that window reaches or how action items are sourced, both of which are non-obvious for an agenda aggregation.

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 no filler, and the operative concept ('upcoming') is front-loaded. It is efficient but borders on under-specification, since no time horizon or item scope is defined.

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 annotations cover the safety semantics. What is missing is the definition of 'upcoming' (time window) and 'action items' — the two terms that determine what the agent will actually get back — which for a zero-parameter tool is the main thing the description should pin down.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description does not need to compensate for any schema gap.

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

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

The description states a concrete verb-resource pair: it returns upcoming interviews and action items, so the agent can infer an aggregated 'what's next' view rather than a raw list. It does not, however, differentiate itself from nearby siblings such as following.digest.get or inbox.list, which overlap in intent.

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 only cue about when to call it is the word 'upcoming', which implies a time-scoped summary, but there are no explicit conditions, no exclusions, and no pointer to alternatives in a sibling set that includes digests and inbox lists. The agent has to guess where this fits relative to those tools.

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 the annotations by disclosing asynchronous processing, source-support detection during refinement, and the side-effect boundary ('adds to the shared index, not to Following'). It does not say what happens when the URL is unsupported or the submission fails, which is the main remaining behavioral gap.

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

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

Four short sentences, front-loaded with the action and its input constraint, followed by behavior, scope, and next step. No filler or repetition of 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 no explanation, and the description correctly routes the agent to companies.submissions.get for status. Missing is any note on failure/unsupported-source outcomes, which matters for an open-world async submission.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning; it does add real constraints for careers_url (public, HTTPS, user-supplied or confirmed) but says nothing about company_name beyond it being implied by 'missing company'. Partial compensation for the coverage gap.

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

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

States a specific verb and resource ('Submit a missing company') and pins the required input ('public HTTPS careers URL'). It is clearly distinguishable from siblings: it explains this writes to the shared index rather than Following, and contrasts with companies.submissions.get.

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 trigger conditions are given: the company is missing, and the URL must be supplied or confirmed by the user. The description names the follow-up alternative (companies.submissions.get for progress) and the separate follow path, so an agent knows both what to call next and what not to conflate with this call.

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 the description correctly spends its words on the status state machine and an agent-facing caution not to claim the company was added or invent jobs while work is in progress. It stops short of saying where submission_id comes from or whether polling is rate-limited.

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

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

Four short sentences, front-loaded with the purpose then the status contract, with no filler. Every sentence supplies actionable 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-shape explanation is unnecessary, and the description covers status interpretation and the anti-hallucination guard. The one real gap is how to obtain the required submission_id, which matters because the tool cannot be invoked without 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 description coverage is 0% for the single required parameter, so the description must compensate and does not: submission_id is never mentioned, and there is no hint that it comes from companies.submissions.create. An agent must infer both the identifier's origin and its format.

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 (read company submission progress), which separates it from the write-side sibling companies.submissions.create. It does not explicitly name or contrast a sibling, 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?

It gives explicit per-state guidance: queued/detecting/processing means wait, ready means re-search by company name, unsupported and failed each have defined meanings. That is a clear when-to-proceed/when-not-to-proceed routing rule, which is exactly what an agent needs.

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 safety (readOnlyHint, idempotentHint, non-destructive, closed-world), so the bar is lower; the description still adds the useful empty-state behavior ('data is null if no schedule is configured'). It does not add auth or rate-limit context, but nothing needed is contradicted.

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

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

Three short sentences, front-loaded with the purpose, then the empty-state semantics, then the sibling routing. Nothing is redundant.

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

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

With an output schema present, return-shape detail is not required, and annotations supply the safety profile. The description covers the two things structured fields don't: the null empty-state and where filter management lives.

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; there is nothing about parameters that needs explaining and the description doesn't waste space on it.

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

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

States a specific verb (Read) and resource (user-wide Following email digest schedule), and explicitly distinguishes this read tool from the sibling mutation tool following.update, which handles company match filters.

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?

Names the alternative explicitly ('Company match filters are managed separately with following.update') and thus routes the agent correctly. It doesn't state prerequisites or when-not-to-use beyond that single split, so it stops just short of a 5.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, open-world. The description adds genuinely non-structured context: a plan entitlement requirement (Plus/Student), the user-wide blast radius, and that existing schedules support patching rather than replace. It does not state what happens on entitlement failure or how conflicts between frequency and weekday are resolved.

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

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

Three tight sentences: purpose first, then eligibility, then parameter requirements. No filler, and the constraints are front-loaded before the per-field guidance.

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

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

An output schema exists, so return values need no explanation, and the mutation profile is covered by annotations. The remaining gap is edge-case semantics for a fully-optional 4-param mutation (all defaults, partial patch interactions), which matters slightly given required=0.

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

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

Schema coverage is 0% and the schema carries only bare types/min-max, so the description has to carry the load — and it largely does: hour 0–23, weekday with Sunday=0, timezone as IANA, frequency of daily/weekly, plus the conditional rule that weekday applies 'when weekly'. It omits defaults and what happens to weekday when frequency is daily.

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: 'Set the user-wide Following email digest schedule'. The 'user-wide' scope qualifier and the schedule object distinguish it cleanly from sibling reads like following.digest.get and from following.pause/resume, which act on delivery rather than schedule.

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?

'after the user requests it' and 'Requires Plus or Student' give a clear consent gate plus an eligibility prerequisite, and the description tells the agent which fields a new schedule needs versus patching an existing one. It stops short of naming an explicit alternative (e.g. following.digest.get for reading the current schedule), so it is a strong 4 rather than a 5.

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

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

Annotations already declare non-read-only, non-destructive, non-idempotent, closed-world. The description adds genuinely new behavior: following applies to future openings only, does not collect historical matches, and does not attempt to submit an unknown careers page. It does not address what happens on a repeat follow of an already-followed company, despite 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?

Three tight sentences, front-loaded with purpose, followed by sourcing guidance and then scoping caveats. No filler and no repetition of schema 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 an output schema present, return values need no explanation, and the description covers the two hard parts: where company_id comes from and what the filters mean. Missing only the repeat-follow behavior for a non-idempotent mutation, which is a minor 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 coverage is only 50% and company_id has no schema description, but the description compensates by explaining its three valid sources. The filter guidance ('specify at least one match', '[{}] follows all new openings') reinforces the minItems semantics, though most detailed filter semantics already live 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 and resource ('Follow an indexed company') plus the concrete payoff ('future matching openings and company recommendations'). It also distinguishes itself negatively from a related action ('does not submit an unknown careers page'), so an agent can separate it from companies.submissions.create without opening the schema.

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

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

It tells the agent where company_id must come from (Search, a ready submission, or a recommendation candidate_company.id) and how to express a catch-all follow ('[{}] follows all new openings'), plus an explicit exclusion. It stops short of naming a sibling alternative for the case where the user wants historical or ad-hoc matching.

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 and closed-world, so the safety profile is covered elsewhere. The description adds one genuinely useful behavioral fact — the whole list comes back with no pagination — plus the returned fields, but says nothing about ordering, size limits, or what happens with zero follows.

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

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

Three sentences, front-loaded with the action and payload, then the no-pagination caveat, then the routing hint. Nothing is repeated from annotations and no sentence is filler.

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

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

Output schema covers the return shape and annotations cover the safety profile, so the description only needed to add scope and routing — which it does. It stops short of clarifying ordering or how 'state' and 'filters' should be interpreted, a minor gap for a zero-parameter listing tool.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The schema imposes no filtering or pagination options, which is consistent with the stated full-list behavior.

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

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

States a specific verb and resource ('List all followed companies') and enumerates what each entry contains: filters, state, unread counts. It also draws the boundary against job search, so an agent can tell which concept it is retrieving without inspecting the schema.

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

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

The closing sentence routes the agent correctly: following is for future matching openings, Search is for jobs already indexed. That is real when-to-use-this-vs-alternative guidance, though it doesn't address the nearest sibling, following.openings.list, which operates on the same followed companies.

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, safe behavior. The description adds non-obvious semantics: what meta.unread_count/read_count and meta.filtered_count actually count relative to filters, and which identifiers to use for follow-up actions.

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

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

Three dense sentences, front-loaded with the core purpose and scoping. Every sentence adds practical value for an agent using the results.

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 usefully clarifies meta-field behavior and identifier use. The main remaining gap is explicit routing versus sibling tools, which is a usage-guidance issue rather than a completeness failure.

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 71%, so the baseline is 3. The description explains the tab default and refers to 'selected follow', but adds little about q, location, department, page, or limit beyond what the schema already documents.

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: read matching openings from followed companies. The 'followed companies' scope distinguishes it from broad search tools, though it does not explicitly name a sibling alternative.

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 useful post-retrieval guidance — row id for marking read, opening.id for details or board — and notes the default tab. However, it does not say when to choose this over alternatives like search.company_openings or openings.get, so selection guidance is only implied.

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

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

Adds substantial context beyond the annotations: it discloses that the operation spans every page and includes openings hidden by view filters (non-obvious blast radius), that the API returns no affected count so the agent must not fabricate one, and that user confirmation is expected. These are exactly the behavioral facts annotations (readOnlyHint/destructiveHint/idempotentHint) do not 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?

Four short sentences, front-loaded with the verb and scope rules, then the blast-radius caveat, the confirmation requirement, and the return-value warning. Every sentence carries distinct information with no 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?

Even though an output schema exists, the description usefully warns that no affected count is returned, preventing hallucination of results. Combined with the scope and confirmation guidance, an agent has everything needed to call this destructive-adjacent bulk mutation correctly.

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

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

Schema coverage is 50% and the uncovered parameter is follow_id, whose semantics the description explains well (omitting it means every followed company). The schema note 'Follow ID from following.list, not company.id' is reinforced, but the description does not explain the required 'confirmed' const flag, leaving that contract implicit.

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

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

States a specific verb (mark all unread openings as read) and resource, and explicitly names the two scopes: one follow vs. every followed company when follow_id is omitted. This differentiates it from the singular sibling following.openings.mark_read 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?

Gives a clear usage condition — confirm scope with the user first — and contrasts the two call modes via follow_id presence/omission. It stops short of naming the sibling mark_read as the narrow alternative, so routing between the two is partly inferred.

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

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

Annotations already declare this is a non-destructive, idempotent, non-open-world mutation, so the safety profile is covered structurally. The description adds no context about what marking read actually changes (unread counts, digest state) or whether it is reversible, leaving a modest gap for a 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?

Two short sentences, front-loaded with the action and followed immediately by the one disambiguation that matters. No filler, no restatement of the name.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. Combined with the id guidance, the definition is sufficient to call correctly; only the downstream effect of the write is left 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 coverage is 0% and the single parameter is just typed as string, so the description carries the full burden. It resolves the key ambiguity by naming the correct source of follow_opening_id and explicitly excluding the nested opening.id — the main way this call would fail.

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 concrete verb and resource: mark a single Following row as read. The word "one" implicitly contrasts with the sibling following.openings.mark_all_read, though it never names that sibling or inbox.mark_read 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?

Gives an explicit sourcing rule for the input (take the id from following.openings.list, not the nested opening.id), which is exactly the mistake an agent would make. It does not, however, spell out when to prefer this over following.openings.mark_all_read.

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

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

Annotations already establish non-destructive, idempotent, non-read-only behavior, yet the description still adds real value by spelling out the blast radius: the follow is not deleted, shared company indexing is unaffected, and other follows are not paused. It does not state how the pause is lifted, but following.resume covers that path.

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 waste, with the core action front-loaded and the scope limits immediately after. Nothing is repeated from the schema or annotations.

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, the single parameter is fully documented, and the description closes the main ambiguity an agent would have about side effects. Nothing needed to invoke this correctly is missing.

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

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

There is a single required parameter and the schema documents follow_id at 100% coverage with a valuable disambiguation ('not company.id'). The description adds nothing about the parameter, but per the baseline rule for full coverage a 4 is appropriate given it is a one-parameter tool.

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 (pause) and a specific scope (future matching openings for this follow), and explicitly distinguishes the action from deletion. It does not name the sibling tools it complements (following.resume, following.unfollow), so an agent must infer the pairing from the sibling 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 implies the usage condition (you want to stop matching openings without removing the follow) and draws negative boundaries around company indexing and other follows. However, it never names following.resume or following.unfollow as alternatives, so the when-to-use-this-vs-that guidance is only implied.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the mutation/safety profile is fully covered. The description adds only the 'paused' precondition; it says nothing about what happens if the follow is not paused, whether resume reverses cleanly, or what state results.

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 clause with zero filler; every word contributes to identifying the action and its target state.

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, one well-documented parameter, and rich annotations, the minimum needed to call the tool correctly is present. Still missing is the failure mode when the follow is not paused and where in the follow lifecycle the resume lands, which matters for a state-transition tool.

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 already carries the crucial disambiguation ('Follow ID from following.list, not company.id'). The description adds no parameter meaning of its own, so 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 ('Resume') and resource ('company follow') plus the required precondition state ('paused'), which implicitly separates it from the sibling following.pause. It does not name an alternative tool explicitly, so it stops short of a 5.

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

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

Usage is only implied: the word 'paused' signals the tool applies to follows currently in a paused state, and the inverse sibling following.pause exists but is never referenced. No explicit when-to-use/when-not guidance or prerequisite (e.g., 'call after following.list') is given in the description.

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, so the description earns credit for going further: it discloses exactly what is destroyed (Following feed, recommendation source) and, importantly, what is preserved ('Board jobs remain'). The user-confirmation requirement is a behavioral obligation not encoded in the annotations or schema.

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

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

Four short sentences, front-loaded with the action and its consequences, then the confirmation rule, then the alternative. Nothing is repeated from the annotations and every sentence changes agent behavior.

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

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

For a destructive two-parameter mutation with rich annotations and an output schema, everything an agent needs is present: what is removed, what survives, that confirmation is mandatory, and which sibling covers the softer action. No remaining informational gap affects 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?

The description says nothing about either parameter. The schema's follow_id description already carries the essential disambiguation ('Follow ID from following.list, not company.id'), and confirmed is a const-true gate that is largely self-explanatory, so the schema does the heavy lifting at 50% coverage. No added meaning in the description, but no real gap either.

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 ('Unfollow a company') and immediately names the concrete side effects: removal of the Following feed and the recommendation source. It also distinguishes itself from the closest sibling by naming following.pause as the non-destructive alternative.

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 precondition ('Confirm with the user first') and an explicit alternative for the adjacent intent ('To pause temporarily instead, use following.pause'). An agent can decide between unfollow, pause, and resume without opening another schema.

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

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

Annotations already cover idempotency and non-destructiveness, and the description adds beyond them: other follow settings are untouched, and there is a pending state where old unread counts may change — a real side effect disclosed up front. It leaves minor gaps (whether the old filter set is lost immediately or after pending completes), 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?

Four short sentences with the core replace semantics front-loaded, then scope, then the empty-filter shorthand, then the pending side effect. No sentence is redundant and nothing important is 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?

With annotations, an output schema and full parameter coverage already present, the description only needs to carry the non-structured behavior, and it does: replacement semantics, unaffected settings, and pending/unread consequences. A small gap remains around preconditions (does the follow need to be active or unpaused).

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 itself carries the detailed semantics (OR groups vs AND fields, remote tri-state, market slugs, compensation units). The description only repeats the [{}] shorthand and the complete-set-not-patch point already stated in the filters description, so it adds little at the parameter level.

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?

'Replace all match filters for a followed company' gives a specific verb (replace), resource (match filters) and scope (followed company), and the replace-not-patch framing separates it from incremental update tools. It never names a sibling as an alternative, so it stops short of full 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?

It clarifies usage for the edge case 'Pass [{}] for all new openings', which is genuinely useful. However there is no explicit when-to-use / when-not guidance relative to siblings such as following.follow, following.pause or following.digest.update, so selection context is only implied.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is largely covered. The description adds a real behavioral requirement not in the annotations: user confirmation must happen before the call. It does not disclose reversibility or mention that inbox.undo exists as a recovery path, which matters for a destructive 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 with the action front-loaded and the prerequisite second; nothing is padded. The first clause ('Keep ... as-is') is slightly indirect phrasing for what is a finalization step.

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 rich, so the description needn't explain returns or safety. What it does provide — the user-confirmation gate — is the key missing piece an agent would otherwise get wrong. Only the absence of sibling routing and recovery guidance keeps it below 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 both `ids` and `confirmed` are already documented, giving a baseline of 3. The description's 'confirm the specific items' loosely ties to both parameters but adds no format or batching detail beyond the schema (e.g., the 1-200 item limit).

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

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

The description names a specific action ('keep auto-applied inbox items as-is and finalize the automatic action'), which is clearly distinct from decline/dismiss/apply_suggestion siblings. It is a clear verb+resource statement, though it never names a sibling to contrast with 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?

It states one prerequisite ('confirm the specific items with the user first'), which is genuinely useful. However it never says when to choose this over inbox.decline, inbox.dismiss, inbox.apply_suggestion, or inbox.undo, leaving the agent to infer the routing.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavioral context: what the suggestion may entail (board addition, rejection) and the requirement to confirm with the user first. It stops short of describing reversibility or permission requirements.

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

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

Two sentences with zero waste. The core action is front-loaded, and the safety confirmation requirement 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?

With rich annotations, full schema coverage, and an output schema, the description carries only the burden of stating purpose and the confirmation prerequisite. It does that adequately; the only gap is the lack of sibling differentiation, which matters less given clear inbox-prefixed naming.

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% — both item_id and the const-true 'confirmed' parameter are documented in the schema, including the requirement that confirmed must be true after user approval. The description adds no parameter-level 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?

The description states a specific verb and resource ('Apply an inbox item's suggested action') and gives concrete examples (adding an application to the board, recording a rejection) that clarify what 'suggestion' means. It does not explicitly distinguish itself from siblings like inbox.decline or inbox.dismiss, 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?

It provides one explicit usage rule — confirm the specific action with the user first — which is valuable. However, it gives no guidance on when to choose this tool over inbox.decline, inbox.dismiss, inbox.acknowledge, or inbox.undo, leaving alternatives 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 openWorldHint=true, but the description adds the crucial undisclosed detail that it may SEND real email from the user's address depending on preference. It does not say whether queued declines can be cancelled or reversed, which matters for a destructive, non-idempotent 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?

Three short sentences: purpose first, side effect second, safety gate last. Every clause carries information an agent needs; nothing is repeated from the schema or annotations verbatim.

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 full schema, rich annotations, and an output schema, the description covers the pieces structured data cannot: the conditional email send and the approval precondition. Only the reversibility/undo path and batch-size implications are left implicit.

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

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

Schema coverage is 100%, so the baseline is 3, but the sentence 'Depending on the user's preference this SENDS email' gives real meaning to the preference enum that the schema only labels ('Send preference to apply'). The approval wording also reinforces the const-true 'confirmed' gate.

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 ('Queue decline replies to recruiter outreach'), which clearly separates it from inbox.draft_reply and inbox.send_reply. It also flags the surprising twist that queueing may actually transmit mail, so an agent knows exactly what class of operation this is.

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, strong gating condition: 'Only call after the user explicitly approved declining these specific conversations.' It does not name alternatives (e.g. draft_reply when the user has not decided, or undo after a mistaken batch), so it stops just short of full routing 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?

Annotations already declare destructiveHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description earns credit by disclosing a real side effect beyond annotations—that it also marks the mail read in Gmail—which the agent could not otherwise infer. It omits reversibility/undo (an inbox.undo sibling exists).

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

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

A single, tight sentence that front-loads the core action and appends the material side effect in parentheses. No wasted 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 rich annotations, full schema coverage, and an output schema, the remaining burden is light. The description covers the action and its key side effect but leaves the acknowledge/decline/mark_read disambiguation to the agent, a minor gap for a 2-param tool.

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 (ids, confirmed) are documented in the schema, including the confirmation gate. The description adds no additional parameter semantics, 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 ('Dismiss inbox items') plus a side effect ('marks the mail read in Gmail'). However, it does not differentiate from closely overlapping siblings like inbox.acknowledge, inbox.decline, or inbox.mark_read, which an agent could easily confuse with dismissing.

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?

'Items you are not acting on' implies a usage context, but with several near-identical siblings (acknowledge, decline, mark_read, recommendations.dismiss) the description offers no explicit when-not or alternative naming. Usage is only implied, not routed.

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, and non-destructive. The description adds genuinely new information: the output is HTML for review and nothing is sent, clarifying the side-effect profile in concrete terms beyond the hints.

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 purpose, with zero redundant or filler text.

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-only tool with rich annotations and an output schema, the description covers purpose, output format, and side effects. Only minor gaps (e.g., what the AI does with 'kind') remain.

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 enum description for 'kind' already explains decline vs interested. The description adds nothing about either parameter, 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 and resource: 'Generate an AI reply draft for an inbox item.' The clause 'it does not send anything' implicitly distinguishes it from inbox.send_reply, though the sibling is not named 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?

The draft-for-review / does-not-send framing gives a clear usage context that routes the agent away from inbox.send_reply. No explicit when-not conditions or named alternatives are given, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine value by disclosing that related job and application data are bundled in the response, but says nothing about whether those relations can be null or how missing items are handled.

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 zero filler; the scope and the relation expansion are packed into one 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?

An output schema exists so return values need not be explained, and annotations cover the safety profile. For a one-parameter read, the only real gaps are nullability of the related job/application and error behavior.

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 (item_id) with 100% schema description coverage, so the schema already carries the semantics. The description does not add format, provenance, or source guidance (e.g., where an item_id comes from).

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 ('Get') plus resource ('one inbox item') and scope ('one'), and it adds that related job and application records are returned with it. That distinguishes it from inbox.list, but 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?

Usage is only implied by the singular 'one inbox item' versus siblings like inbox.list and inbox.get_thread. There is no explicit statement of when to prefer this over those alternatives or what happens when the id is unknown.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered without description help. The description's use of 'full' adds a small hint that the whole thread rather than a truncated view is returned, but nothing is said about whether reading marks the item read, pagination, or attachment handling.

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

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

One sentence, front-loaded with the verb and resource, zero wasted words. Nothing padded or repeated from the schema.

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

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

With rich annotations, a 100% documented single parameter, and an output schema covering return values, the description is close to sufficient. The remaining gap is the lack of explicit contrast with inbox.get for an agent choosing between them.

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

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

Schema coverage is 100% with a single required parameter documented as 'Inbox item id', so the schema carries the semantics. The description only restates 'for an inbox item' and adds no format, sourcing, or ID-resolution detail beyond that.

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 ('full email thread') scoped to 'an inbox item', which is clearly distinct from siblings like inbox.get or inbox.list. It stops short of explicitly contrasting itself with inbox.get, which fetches a single item, so the differentiation from that closest sibling is only inferable.

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: the word 'full' hints that this is the right tool when the complete conversation is needed rather than the single item returned by inbox.get, but no when-to-use condition or alternative is named. An agent must infer the routing decision from sibling names alone.

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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds the useful framing that results are pre-filtered/matched by Refine rather than raw mailbox contents, but says nothing about ordering or pagination behavior beyond what the schema documents.

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 trailing parenthetical partially repeats the tab enum values, which is the only mild 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?

With an output schema present, full schema coverage and complete annotations, the description needs only to establish what the listing represents, which it does. It could add a note on the default tab/limit behavior, but nothing essential for a correct call 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%, with enums documented for tab, shelf and status, so the schema carries the parameter burden. The description only echoes the three tab categories already enumerated in the schema, adding no extra detail on status, shelf, unread or pagination 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 ('List') and resource ('email conversations Refine matched to your job search'), and the parenthetical enumerates the three tab categories. It is distinguishable from inbox.get / inbox.get_thread by being a collection operation, though it never names those siblings 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?

Usage is implied by the name and the 'matched to your job search' framing, but there is no explicit guidance on when to call this versus inbox.get, inbox.get_thread, or inbox.refresh, and no mention of prerequisites such as needing a connected account.

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 some behavioral detail by specifying that this is a flag-clearing operation, not a deletion or full-read state change. It does not contradict the existing annotations, and the idempotent, non-destructive hints are already covered by annotations. It could add more context about reversibility or side effects, but the current level is acceptable.

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?

Seven words, with no fluff or repetition. The key verb and object are front-loaded, making the intent immediately 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 one-parameter, idempotent, non-destructive operation with an output schema and complete parameter documentation, this description is mostly sufficient. The main missing piece is usage differentiation from similar inbox actions, but the core behavior is clearly specified.

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 only parameter, item_id, is fully described by the schema ('Inbox item id'), and schema description coverage is 100%. The description does not need to add much, so it gets the baseline score without adding redundant parameter details.

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?

Description uses a specific verb ('Clear') and a specific resource ('an inbox item's unread-reply flag'), going beyond the generic title 'Mark read'. It meaningfully separates this from siblings like inbox.accept, inbox.decline, inbox.dismiss, and inbox.acknowledge.

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 explicit guidance is given about when to use this tool versus closely related sibling tools such as inbox.acknowledge, inbox.dismiss, or inbox.accept. The intended scenario is only implied by the verb 'clear', not stated.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the agent knows this side-effects an external system and is not repeatable cheaply. The description corroborates this by saying it goes out to Gmail immediately, but it adds nothing about rate limits, blocking behavior, or what a refresh does to existing state — 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?

A single front-loaded sentence with the action first and the return value second. No filler.

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

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

With an output schema covering return values, zero parameters, and annotations covering the safety profile, the description carries what it must. It stops short of saying whether the call blocks until sync finishes, which is the one operational detail an agent might need before calling a non-idempotent external fetch.

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 there is nothing for the description to disambiguate; the baseline applies. The description correctly implies no scoping arguments are 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?

A specific verb+resource: 'check Gmail for new mail now' plus a note on what comes back. It separates an on-demand fetch from passive listing tools like inbox.list, but it never distinguishes itself from the sibling inbox.sync_status, whose name reads almost identically to the stated return value.

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 word 'now' implies this is the on-demand trigger versus background syncing, which is useful context, but there is no explicit when-to-use, no exclusion, and no pointer to inbox.sync_status as the read-only alternative.

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

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

Annotations already flag destructiveHint, openWorldHint and non-idempotency, so the bar is lower, but the description adds meaningful context the annotations cannot: this sends to a real person from the user's own address, making the action externally visible and irreversible. It omits delivery failure or rate-limit behavior, but the key risk is surfaced.

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 zero waste, ordered so the action and its real-world consequence come before the gating condition.

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 and full parameter descriptions are present, and the description supplies exactly the missing piece an agent needs: the human-approval gate before an irreversible send. Nothing required to call it safely is absent.

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

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

Schema coverage is 100% and every parameter, including the confirmed const-true gate and draft_kind enum, is already documented in the schema. The description reinforces the 'exactly as approved' semantics of body but adds no format or usage detail beyond that, 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 and resource: sends an email reply via the user's Gmail. It is distinguishable from inbox.draft_reply by intent, but the description never names the draft sibling that would normally precede it, leaving that differentiation implicit.

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, strong precondition: only call after the user has seen the exact body and explicitly approved. It does not spell out the alternative workflow (draft first via inbox.draft_reply) or when not to call, so it stops short of full routing 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds per-account Gmail scope and the returned status fields, but does not go beyond that with auth requirements, rate limits, or sync-state caveats.

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 wasted words. It delivers resource, scope, and returned data 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?

Given zero parameters, rich annotations, and an output schema, the description is complete enough for an agent to call the tool correctly. It states what the status covers without needing to explain return values or safety behavior.

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 has zero parameters, so the baseline is 4. The description appropriately avoids describing nonexistent parameters while clarifying that status is per-account.

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 resource (Gmail synchronization status) and scope (per-account), and identifies the information returned (current progress and last sync time). It is clearly distinguishable from sibling actions like inbox.refresh or integrations.connect_google.

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: an agent can infer this is the read-only status check, but the description does not explicitly state when to use it versus inbox.refresh or other inbox tools. No alternatives or preconditions are mentioned.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds the concrete consequence — it can delete a board record that the automatic action created — which is exactly the kind of beyond-annotation context that matters for a destructive 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 sentences, front-loaded with the action and immediately followed by the risk and the required precaution. 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 and fully documented parameters mean the description only needs the action and its side effect, which it supplies. Minor gaps remain: what happens if the original action wasn't auto-applied, and whether an undo can itself be reverted.

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

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

Schema coverage is 100%, so both item_id and confirmed are already documented, including the const: true constraint. The description reinforces the confirmation requirement ('confirm with the user first') but adds no format or edge-case detail, 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 (undo) and resource (auto-applied inbox action), which distinguishes it from nearby inbox siblings like apply_suggestion, dismiss, and decline. It doesn't explicitly contrast with those siblings, but the 'auto-applied' qualifier narrows it well.

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 one clear procedural instruction ('confirm with the user first'), which is real usage guidance. It stops short of saying when to reach for this versus inbox.dismiss, inbox.decline, or inbox.acknowledge, or what to do if the action wasn't auto-applied.

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, indicating mutation. The description adds crucial behavioral context by stating 'This changes the user's real email subscriptions,' emphasizing real-world impact beyond the app. It also reinforces the confirmation requirement. However, it does not detail failure modes (e.g., sender lacking list-unsubscribe support) or long-term effects, though these are somewhat covered by openWorldHint. With annotations present, this description adds meaningful context without contradicting them.

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

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

The description is two sentences long and front-loads the core action ('Unsubscribe the user...'), followed by a warning about real-world impact, then usage guidance. Every sentence earns its place with no fluff or repetition. It is concise and well-structured for quick agent parsing.

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 description is complete for a destructive, confirmation-gated tool. It covers what the tool does, the mechanism (one-click list-unsubscribe), the need for explicit user confirmation, and when not to use it. An output schema exists (per context) so return values do not need explanation. The only minor gap is that it does not mention potential failure conditions or whether the action is reversible, but given the output schema and existing annotations, these are not critical.

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%, with item_id defined as 'Inbox item id' and confirmed as 'Must be true, and only after the user explicitly approved.' The description reinforces the confirmed parameter ('confirm with them before calling') but adds no additional meaning beyond the schema. Since the schema already documents both parameters adequately, a baseline score 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 explicitly states the tool's action: 'Unsubscribe the user from this sender's mailing list via one-click list-unsubscribe.' It identifies the resource (the user's subscription) and the condition (this sender). It also differentiates from siblings by saying 'Use it for unwanted bulk senders, not for a person you can simply decline,' which clearly separates it from tools like inbox.decline or inbox.dismiss.

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 provides explicit usage guidance: it tells the agent to confirm with the user before calling ('confirm with them before calling') and gives a clear selection criterion ('unwanted bulk senders, not for a person you can simply decline'). This directly addresses when to use this tool versus alternatives, leaving no ambiguity about the appropriate 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?

The description adds valuable behavioral context beyond annotations: the connection happens in the browser, no Refine sign-in is required, and the link is tied to the account owner. It clarifies the tool's role as a link generator rather than a direct connection, which is helpful for the agent. No contradiction with annotations; the description's 'get a link' aligns with readOnlyHint=false (since the user performs the actual connection).

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 three sentences, each serving a clear purpose: purpose (what it returns and for what), mechanism (how permission is selected), and security warning. It is front-loaded with the primary action and wastes no words. Excellent conciseness and structure.

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 tool with no parameters and a simple action (retrieving a link), the description is complete. It explains the purpose, the flow, and an important security constraint. The presence of an output schema likely covers the return value, so the description doesn't need to. 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?

With zero parameters, the schema already covers everything (100% coverage by definition). The description does not need to explain parameters, and it doesn't. Baseline for no params is 4, and the description appropriately focuses on output and use, so this score is justified.

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 the tool's function: 'Get a link for the user to connect Gmail to Refine or approve a missing Gmail permission.' It uses a specific verb ('get') and resource ('a link'), and explicitly mentions the two related use cases. This distinguishes it from siblings like integrations.list, which is about listing integrations, not connecting Gmail.

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 provides solid context: it tells the agent it's for connecting Gmail to Refine or approving missing permissions, and that Refine selects the permission. It also includes a critical security caveat: 'Share the link only with the owner of this Refine account.' However, it does not explicitly mention when not to use this tool or name alternative tools, 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 annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is well covered. The description adds useful scope by saying it lists connected Google accounts and their grant status, but it does not add behavioral details such as auth requirements, pagination, or how grant statuses are surfaced.

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 one relevant alternative. Every sentence earns its place.

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

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

For a zero-parameter, read-only listing tool with rich annotations and an output schema, the description is complete enough. It identifies the resource, the returned concept (grant status), and the correct sibling for the adjacent connect action.

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 has zero parameters, so the baseline score is 4. The description appropriately does not waste space explaining parameters that do not exist.

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 specific verb and resource: 'List connected Google accounts and their grant status.' It also explicitly distinguishes this tool from the sibling integrations.connect_google, so an agent can identify its function without opening the schema.

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

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

It clearly routes the connect case to integrations.connect_google, which is the most relevant alternative. It does not state explicit exclusions or when-not conditions, but for a simple read-only list tool the usage context is sufficiently clear.

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 non-read-only, open-world, non-idempotent, non-destructive, so the safety profile is covered structurally. The description adds nothing beyond that: no mention of duplicate detection (relevant since idempotentHint is false), validation failure behavior, or what creation triggers.

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 – nothing superfluous, but also nothing front-loaded beyond the bare purpose. Brevity here reflects under-specification rather than disciplined editing.

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

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

For an 8-parameter creation tool with no idempotency, the description omits required-field emphasis, duplicate handling, and side effects. The output schema covers return values, but the behavioral gaps around creation still leave an agent under-informed.

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 all 8 parameters, so the schema fully documents fields, formats and the two required ones. The description adds no meaning 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?

The verb 'Add' plus resource 'job' is clear enough to distinguish it from jobs.update/jobs.get/jobs.list by name alone. However, 'to your journey' is vague marketing phrasing that adds no concrete scope, and the sentence largely restates the tool name.

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

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

There is no guidance on when to use this versus jobs.update (existing job) or openings.add_to_board, nor any prerequisite such as required title/company or duplicate handling. The agent must infer everything from the name and sibling list.

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

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

Annotations already declare this is non-read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: it hides the job from the active board and explicitly does not record a rejection or close the application, which helps an agent understand side effects beyond the annotations.

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 wasted words. It states the action and the key exclusions 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?

The description is mostly complete for an archive tool with rich annotations, a complete one-parameter schema, and an output schema. It could mention reversibility or the existence of jobs.unarchive, but the core behavioral picture is clear.

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 job_id is already documented in the schema. The description adds no parameter-level detail, so the baseline score 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 states a specific verb and resource: hide/archive a job from the active board. It also distinguishes the action from recording a rejection or closing an application, which clarifies the semantic boundary, though it does not explicitly contrast with jobs.delete.

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 'without recording a rejection or closing the application' implies when to use this tool, but there is no explicit 'use this when' guidance or named alternative such as jobs.delete or jobs.unarchive. Usage is inferable but not fully 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?

Beyond the destructiveHint and readOnlyHint annotations, the description adds key behavioral context: the deletion is permanent, affects both the job and its application, cannot be undone, and requires user confirmation. This materially helps an agent understand the consequences of invoking the 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 sentences carry all essential information with no filler. The destructive consequence and confirmation requirement are front-loaded, and the alternative tool is mentioned succinctly in the second sentence.

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 destructive tool with two well-documented parameters, a rich annotation set, and an output schema, the description covers the critical operational context: irreversibility, cascade effect, confirmation requirement, and the relevant alternative. 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%, with both job_id and confirmed already described in the input schema. The description reinforces the deletion behavior but adds no new parameter-level meaning beyond what the schema provides, so the baseline score 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 states a specific verb and resource: 'permanently delete a job and its application from the board.' It also differentiates itself from the sibling jobs.archive by explicitly naming the alternative usage, making the tool's scope unmistakable.

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 when-to-use instruction: confirm with the user first, and it explicitly tells the agent to use jobs.archive instead when the intent is to hide a job without recording a rejection or closure. This is direct guidance for tool selection.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, and the description adds no further behavioral context such as permissions, rate limits, or what 'details' includes. It is consistent with the annotations but contributes almost nothing 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?

The definition is a single sentence with no filler, and the core action is front-loaded. It is as concise as possible for a simple getter.

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 read operation with full schema coverage, rich annotations, and an output schema, the description is complete enough to call the tool correctly. It is thin on selection context, but the output schema removes the need to explain return values.

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%, with job_id documented as 'Job id'; the description adds no format, syntax, or semantic nuance beyond that. Since the schema fully documents the only parameter, the baseline score 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 states a specific verb and resource: get details of a specific job. It distinguishes a single-job getter from broad listing by saying 'specific job,' but it does not explicitly differentiate from siblings such as jobs.list, jobs.update, or jobs.refresh.

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 required job_id parameter and phrase 'specific job' imply usage when the job identifier is already known. However, the description gives no explicit when/when-not guidance and names no alternatives, so the agent must infer the distinction from sibling names.

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 disclose this is a non-destructive, non-idempotent write with a closed-world scope, so the safety profile is covered. The description adds nothing beyond that — it does not say whether repeat calls create duplicates, whether logging triggers notifications, or what side effects follow.

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

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

One front-loaded sentence with zero waste, but for a five-parameter mutation tool it is under-specified rather than efficiently concise. Brevity here costs more than it saves.

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 cover the safety profile, so the description needn't explain return values. Still, for a mutation that writes interview records, missing guidance on duplicates and on the create/update boundary leaves a real 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% and all five fields (name, notes, job_id, location, scheduled_at) are documented with examples and an ISO 8601 pattern. The description adds no parameter meaning beyond the schema, 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?

The verb 'Log' plus the resource 'an interview for a job' gives a clear, specific purpose that an agent can map to a create operation. It stops short of distinguishing itself from siblings like jobs.interviews.update or jobs.interviews.delete, which also operate on the same resource.

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 use this rather than jobs.interviews.update, nor any prerequisites (e.g. whether the job must already exist or be in an applied state). The agent must infer the create-vs-update split from tool names alone.

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. The description adds the critical detail 'cannot be undone' (reinforcing permanence) and mandates user confirmation, both of which go beyond the structured annotations.

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 a single sentence with no wasted words. It front-loads the action and permanence, then adds the confirmation requirement—every clause contributes.

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 3-parameter delete operation with annotations covering destructive/idempotent behavior and an output schema present, the description provides all necessary context: action, permanence, and confirmation requirement. It could optionally note alternatives, but that is not essential 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?

The schema has 100% parameter description coverage, including the confirmed field's purpose. The description essentially restates the confirmation requirement already in the schema, adding no new parameter-level meaning.

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 ('Permanently delete') and identifies the exact resource ('an interview from a job'). It clearly distinguishes from sibling tools like jobs.interviews.add and jobs.interviews.update by emphasizing irreversibility.

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 instruction 'Confirm with the user first' provides a clear condition for when to invoke the tool, effectively guiding the agent to only call it after user confirmation. While it does not explicitly mention alternatives, the permanent deletion context makes the appropriate situation obvious.

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, destructiveHint=false and readOnlyHint=false, so safety profile is covered. But the description adds nothing: it doesn't say whether omitted fields are left unchanged or cleared, what happens to outcome/rating transitions, or that cancelled_at must pair with cancelled_reason. For a 14-parameter mutation tool this is a real gap.

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

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

A single front-loaded sentence with zero waste, but also zero substance — conciseness here reflects under-specification rather than disciplined editing. There is no structure to speak of because there is only one 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?

With 14 parameters, an output schema, and existing annotations, the description should at minimum state that only supplied fields are modified. Nothing about update semantics, required fields beyond IDs, or interaction between cancelled_at/cancelled_reason is present, leaving the agent to guess at mutation behavior.

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 enum/format constraints are fully documented, so the schema carries the parameter burden. The description contributes no extra semantics beyond 'update', which meets the baseline-3 expectation when coverage is high.

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 specific verb + resource ("Update an existing interview") and, via the tool name, distinguishes itself from jobs.interviews.add and jobs.interviews.delete. It stops short of saying what aspects are updatable or what 'existing' requires, but the core purpose is unambiguous.

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

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

No guidance on when to use this instead of jobs.interviews.add or jobs.interviews.delete, no prerequisites, and no statement of whether partial updates are allowed. The agent must infer everything from the tool name and schema.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering the safety profile. The description adds only 'in your journey' as a scoping hint, with no explanation of pagination defaults, authorization requirements, or ordering behavior.

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

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

The description is a single short sentence with zero waste and is front-loaded. It is appropriately sized for a simple list tool, though 'journey' is left undefined.

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 has rich annotations, complete parameter documentation, and an output schema, so the description does not need to explain return values or safety. However, the vague term 'journey' is never clarified, and the lack of any usage context leaves a small but real gap for an agent deciding when to call this tool.

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%, with both optional parameters (page, limit) fully documented, so the baseline is 3. The description adds no parameter-specific meaning beyond what the schema already provides.

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

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

The description states a clear verb (List) and resource (jobs), and the qualifier 'in your journey' implies scoping to the user's own tracked jobs. It is naturally distinct from mutation siblings like jobs.add or jobs.archive, though it does not explicitly differentiate itself from other list-style 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?

There is no guidance on when to use this tool versus alternatives, no mention of filtering or scoping options, and no exclusions. The only implied usage is that it lists jobs, which is already evident from the name.

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=false, destructiveHint=true, and idempotentHint=true, and the description does nothing to explain any of that. In particular it never clarifies what is "destroyed" by a destructive-hinted operation or whether an application record is created versus a status flipped — exactly the context an agent needs before invoking.

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

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

One short, front-loaded sentence with zero filler. The issue is under-specification rather than verbosity, so it does not lose points for wasted text.

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 needn't be described, but for a mutation with destructiveHint=true and no annotations explaining side effects, the description should say what changes and whether it is reversible. That gap is material given the surrounding offer/submission 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% with a single required job_id, so the schema already carries the parameter meaning. The description adds nothing (e.g. whether job_id is the posting id or the user's tracked-job id), 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?

The verb+resource ("Mark a job as applied") is understandable, but it is essentially a restatement of the tool name and adds no scope or mechanism detail. It does not distinguish this from siblings like jobs.update or companies.submissions.create, which could plausibly also record an application.

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

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

There is no guidance on when to use this rather than jobs.update, companies.submissions.create, or jobs.add. No prerequisites, no exclusions, no mention of what state the job must be in.

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

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

Adds meaningful context beyond the destructiveHint annotation: it explains that this is a major state change that closes out the role search and clarifies an important boundary ('It does not email the employer'). This tells the agent what the action affects and what it does not do, which is exactly the kind of behavioral detail annotations alone cannot convey.

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

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

Three short sentences with no waste: purpose first, then the critical confirmation requirement, then the side-effect boundary. Every sentence earns its place.

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

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

Given the tool's destructive nature and the presence of an output schema and full parameter documentation, the description supplies the remaining essential context: user confirmation is required, the search closes, and no employer email is sent. Nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, and both parameters are documented, including the required confirmation semantics for 'confirmed'. The description adds no parameter-specific guidance, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Accept the offer for a job') and makes the effect clear. It does not explicitly name or contrast with nearby siblings such as jobs.offer.decline, but the action is unambiguous from the name and description.

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?

Provides a clear prerequisite ('confirm with the user before calling') and context ('closes out the search for this role'). It does not explicitly discuss when to choose decline or other alternatives, 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?

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write. The description adds that it records a negotiation event such as a counter or update, which clarifies the domain meaning, but it does not warn about duplicate event accumulation or ordering, which matter for a non-idempotent append 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?

A single front-loaded sentence with no filler. It is efficient, though its brevity means nothing about sequencing or alternatives is ever established.

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 seven parameters, an output schema, and full schema coverage, the structured fields carry most of the burden. The description is adequate but omits the one thing only prose can supply: how this tool relates to the other offer 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 every parameter including salary_cents, bonus_cents, equity_text, and the event_type enum is already documented. The description's 'counter-offer, update, etc.' loosely maps to event_type values but adds no format or unit detail beyond the schema.

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

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

States a specific verb and resource: logging a negotiation event on an offer, with parenthetical examples (counter-offer, update). It distinguishes the tool from the broader jobs.offer.update only implicitly, but the resource+action combination is clear enough to route on.

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 log a negotiation event versus using jobs.offer.update or jobs.offer.delete_negotiation, and no preconditions such as whether the offer must already exist. The agent must infer the situation from the name alone.

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 provide the full safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false). The description does not add anything beyond that profile, even though idempotentHint=false has a practical consequence that it should state: calling this twice creates duplicate offers. It also says nothing about required permissions or what already-existing data the call might overwrite.

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

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

It is a single front-loaded sentence with zero redundancy, and the verb and resource come first. It is efficient, but it is actually undersized for a 17-parameter create 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 and annotations exist, but for a 17-parameter create tool with a rich negotiation-tracking model, the description omits the essential shape of the data: that it tracks initial offers, target asks, deadlines, and next actions. An agent reading only the description would not know what a 'complete' record looks like.

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 every parameter, including the initial_*/target_* negotiation triplets and the cents convention. The description's phrase 'compensation details' loosely maps to the money fields, but it does not explain the initial-versus-target negotiation model that dominates the schema. A 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 states a specific verb and resource: 'Record a job offer'. That distinguishes it from jobs.offer.accept, jobs.offer.decline, and jobs.offer.update, though it never says so explicitly. The clause 'with compensation details' hints at scope, but the 17-parameter schema is far broader than compensation alone (deadline, next_action, notes).

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 says nothing about when to call it, when not to, or how it relates to the many siblings. For example, nothing tells the agent whether to use jobs.offer.update when an offer already exists, or that jobs.offer.add_negotiation handles the initial/target fields after creation.

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, idempotentHint=true, and readOnlyHint=false. The description adds useful context by emphasizing the major state change, requiring user confirmation, and clarifying that no employer email is sent. It does not detail reversibility or downstream effects, but it adds meaningful behavioral context beyond the annotations.

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 two front-loaded sentences with no wasted language. It immediately states the action, highlights the state-change significance, and adds a key side-effect clarification.

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 destructive annotation, full parameter schema, and output schema, the description covers the key agent-facing concerns: user confirmation and no employer email. It could say more about reversibility or what exactly changes, but it is sufficiently complete 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 both job_id and confirmed are already documented in the input schema. The description reinforces the confirmed semantics with "confirm with the user first," but adds little beyond the schema for job_id. This meets the baseline for high schema coverage.

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: "Decline the offer for a job." This is clearly distinct from sibling operations such as jobs.offer.accept, jobs.offer.update, and jobs.offer.delete, and the "major state change" phrasing signals the significance of the action.

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

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

It gives a clear usage condition: confirm with the user first before declining. It also clarifies that the tool does not email the employer, which helps set expectations. It does not explicitly name alternatives such as jobs.offer.accept, but the context is still clear.

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 include destructiveHint: true and idempotentHint: true, but the description adds meaningful context beyond that: it states the deletion is permanent ('cannot be undone'), clarifies that the job record remains, and reiterates the need for user confirmation. This provides a fuller picture of the operation's consequences.

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 two short, purposeful sentences. The first sentence states the action and scope; the second provides usage conditions and consequences. There is no redundancy or fluff; every clause earns its place.

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

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

For a simple two-parameter destructive tool, the description covers all necessary aspects: what is deleted, what is preserved, when to use it, the requirement for confirmation, and irreversibility. The output schema exists to explain return values, and the annotations handle the safety profile. Nothing important is missing.

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

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

The schema already describes both job_id ('Job id') and confirmed ('Must be true after the user confirms permanent deletion') with 100% coverage. The description does not add new details about the parameters beyond reinforcing that confirmation is required, which is already in the schema. Hence the baseline score 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 the verb 'delete' and the resource 'offer recorded for a job', and explicitly notes 'the job stays' to distinguish from jobs.delete. This unambiguously identifies what the tool does and differentiates it from sibling tools like jobs.delete or jobs.offer.update.

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 provides explicit usage context: 'Use only to fix a mistake, and confirm with the user first'. This tells the agent when it is appropriate to call the tool and imposes a confirmation requirement. It does not explicitly name alternative tools, but the condition covers the main decision point.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description states 'remove', which aligns with destructive, but adds no extra behavioral context (e.g., permanence, cascading effects, or the need for confirmation). Since annotations carry the safety profile, this is a minimal but acceptable disclosure.

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

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

The description is a single, direct sentence with no wasted words. It front-loads the action and object clearly. This is concise and well-structured.

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 simplicity, the description is adequate. The annotations cover destructive and idempotent hints, and the schema documents all parameters including the confirmation requirement. However, it lacks any warning about the irreversible nature or any expected outcome, which would be helpful for a destructive operation. Still, the essential information is present.

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 description (job_id: 'Job id', event_id: 'Negotiation event id', confirmed: 'Must be true after the user confirms deletion'). The tool description adds no additional parameter meaning beyond what the schema already provides, so it meets the baseline without enhancement.

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 'Remove a negotiation event from an offer' specifies a clear verb (remove) and specific resource (negotiation event within an offer). It effectively distinguishes from sibling tools like jobs.offer.delete (which deletes the offer itself) by targeting a sub-resource. The meaning is unambiguous and immediately actionable.

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 is provided regarding when to use this tool versus alternatives. There is no mention of prerequisites, such as confirmation flow (despite the confirmed parameter), or any distinction from jobs.offer.delete. The description only states what it does, not when or why an agent should choose it.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description adds no behavioral context beyond the annotations—it does not clarify partial versus full replacement semantics, whether omitted fields are preserved, or any preconditions such as the offer already existing.

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 single sentence is front-loaded and free of filler. It is efficient, though its brevity reflects under-specification rather than a deliberate choice to be concise.

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 17-parameter mutation tool with siblings that handle creation, deletion, acceptance, and negotiation, the description is too thin. Although an output schema and annotations exist, the agent is left without crucial update semantics (partial update behavior, offer existence requirements) needed to call this confidently.

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 17 parameters are already documented in the input schema. The description adds no parameter-level meaning beyond what the schema provides, which is the baseline expectation when coverage is high.

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 clear verb ('Update') and resource ('the offer recorded for a job'), making the operation understandable at a glance. It does not explicitly distinguish itself from siblings like jobs.offer.create or jobs.offer.delete, which keeps it from 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 use this tool versus jobs.offer.create, jobs.offer.accept, or jobs.offer.add_negotiation. The agent must infer that this is the general-purpose offer edit tool from the name alone.

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 mutation (readOnlyHint=false), non-idempotency, and non-destructiveness; the description adds the crucial behavioral trait that the operation is asynchronous and the returned job may remain pending. That non-obvious timing detail is exactly what an agent needs beyond the annotations.

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

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

Two tight sentences, front-loaded with the action and followed by the essential follow-up instruction. No boilerplate or repetition.

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

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

Output schema exists, so return values needn't be explained, and the description covers the one thing the output schema can't convey: the result is likely pending. Nothing needed to invoke 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% with a single required job_id, so the schema carries the parameter documentation. The description adds no format or resolution hints for job_id (e.g. where to obtain the id), which is fine given the coverage 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 ('Queue a job posting to be re-scraped') with clear async semantics. Distinguishes itself from jobs.get, which is named as the follow-up inspection tool, and from jobs.add/jobs.update.

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 this to trigger a re-scrape, then use jobs.get to inspect results. It doesn't explicitly state when NOT to use it (e.g. versus jobs.update or jobs.add), but the async sequencing guidance is actionable.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and closed-world scope. The description adds the state transition target (active board), but does not cover permission requirements, behavior when the job is not archived, or error conditions.

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 sentence with zero waste, front-loading the verb and the effect. Nothing extraneous remains to trim.

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 cover the safety and idempotency profile, so the description need not explain return values. It is complete enough for a one-parameter state-toggle, though the required pre-state is only implied.

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

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

The schema has 100% description coverage for the single job_id parameter, and its meaning is self-evident. The description adds no syntax or format detail 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 ("Restore") and resource ("archived job") plus the outcome ("to the active board"). It is clearly distinguishable from the sibling jobs.archive 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?

Usage is implied: call this to reverse an archive. There is no explicit statement of when not to use it, prerequisites (job must currently be archived), or a named alternative, though jobs.archive is an obvious sibling.

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=false, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: it does not state whether the update is partial (only supplied fields change) or a full replace, nor whether unspecified fields are cleared — the most consequential behavioral detail for a mutation tool.

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

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

Six words with no redundancy, but that brevity comes at the cost of substance; 'in your journey' is unfalsifiable filler rather than front-loaded information. Efficient but under-specified.

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?

This is a 10-parameter mutation tool operating in a context with many overlapping sibling tools. An output schema exists, so return values need no explanation, but the description leaves the partial-vs-full update semantics and job_id requirement entirely unaddressed — 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% with 10 documented params, so the schema carries the parameter burden and baseline 3 applies. The description contributes zero additional semantics and notably omits that job_id is required while the other nine fields are optional.

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 verb 'Update' and resource 'a job' are stated explicitly, which distinguishes it from jobs.archive, jobs.delete, and jobs.mark_applied. However, 'in your journey' is noise and the description never says what aspects are updatable (fields vs. status), leaving it only marginally more informative than the tool name jobs.update.

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 instead of the crowded sibling set: jobs.archive, jobs.unarchive, jobs.mark_applied, jobs.refresh, or jobs.add. An agent has no signal for choosing between a generic field update and the dedicated status-change tools.

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, but the description adds non-obvious behavior the agent cannot see structurally: a duplicate call returns the existing board job, and the call silently marks a matching Following item as read. The side effect on Following state is exactly the kind of disclosure that prevents surprise downstream.

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

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

Three sentences, the primary action front-loaded, with the ID disambiguation placed immediately after. The final sentence bundles two unrelated exclusions and the mark-as-read side effect, which reads slightly compressed but wastes no words.

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