refine

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 description is not required to restate safety. It adds the time-bound 'upcoming' scope but does not clarify what an action item is, how results are ordered, or whether the result set is exhaustive.

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 one short, front-loaded sentence that states the essential action and resource with no filler. Every word 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 tool with annotations and an output schema, the description is nearly sufficient. It communicates the core data being retrieved, though it could add one sentence on when someone should choose this over interviews.list or other agenda-related siblings.

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 0 parameters and schema description coverage is 100%, so there is no parameter semantics burden for the description to carry. The baseline of 4 applies because there is nothing missing on the parameter side.

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 'Get' and the resource ('upcoming interviews and action items'), so an agent can tell what the tool returns. It does not explicitly distinguish itself from siblings like interviews.list or inbox.get, so it misses the highest differentiation bar.

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

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

The description gives no guidance on when to use this tool versus alternatives like interviews.list or inbox.get. It does not state prerequisites, intent, or exclusion conditions, leaving the agent to infer usage from the tool 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 annotation set already covers readOnly=false, destructiveHint=true, and idempotentHint=true. The description adds some context by showing that the action can add or reject a job application, but it does not provide additional behavioral detail such as irreversibility, side effects, or what happens after acceptance.

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 redundant wording. It communicates the core behavior, gives useful examples, and remains compact.

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 one-parameter tool with a complete input schema and an output schema, the description is largely sufficient. It would improve by explicitly differentiating itself from nearby inbox actions, but the current description gives enough context for an agent to understand the high-level operation.

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

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

The schema has 100% coverage for the only parameter, item_id, described as 'Inbox item id'. The description references an inbox item but does not provide additional semantic details beyond the schema. Since schema coverage is complete, 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 identifies the action: applying an inbox item's suggested action, with helpful examples like adding an application to the board or recording a rejection. It is specific about the verb and resource, though it does not explicitly contrast with sibling tools such as inbox.acknowledge, 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 intended usage is inferable: use this tool when you want to apply the suggested action on an inbox item. However, the description does not explicitly state when not to use it or which sibling tool should be preferred for acknowledge, decline, dismiss, or reply operations.

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 idempotent and non-destructive annotations, the description adds context that this tool confirms an automatic action and preserves the item as-is, which is a meaningful behavioral trait not captured in the annotations. The readOnlyHint=false is compatible with the idea of confirming/acknowledging (which may update an acknowledgment flag) and no contradiction exists. The description thus enriches the agent with the intent of the action.

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, focused sentence that front-loads the core action ('Keep auto-applied inbox items as-is') and immediately gives the purposeful clarification ('confirms the automatic action'). It contains no unnecessary words and is highly efficient for an agent to parse.

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 tool with one parameter, an output schema underwriting return behavior, and full annotations, the description is nearly complete. It clearly conveys purpose and non-destructive behavior. The only slight gap is an exact definition of 'auto-applied', which is terminology specific to the domain but may not be self-explanatory to every agent without further context.

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

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

Since the schema already fully describes the single parameter 'ids' with a coverage of 100%, the baseline is 3. The description adds an important constraint: it explicitly ties those IDs to 'auto-applied' inbox items, implying the IDs must correspond to items that were automatically processed. This added semantic clarifies which elements to pass, justifying a higher score, but it's not dramatically more detailed.

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

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

The description clearly states a specific action—'Keep auto-applied inbox items as-is'—and immediately clarifies that it confirms an automatic action. This distinguishes it from sibling tools like inbox.accept, inbox.decline, and inbox.dismiss, which perform different operations on the same item type. The only minor ambiguity is the meaning of 'auto-applied', but the context and parenthetical are enough for an agent to understand the tool's role.

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 strongly implies the use case: when an inbox item has been auto-applied and the user wants to retain that action, they should call this tool to confirm it. However, it does not explicitly state when not to use it (e.g., for items not auto-applied, or when the user wishes to accept or decline instead). This makes the guidance vivid but not exhaustive, so it's slightly below the highest bar.

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 readOnlyHint=false, but the description adds real behavior context: it may actually SEND email from the user's address and is gated on user approval. This explains a side effect not fully represented by 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, each earning its place: the first defines the action and the key side effect, the second captures the mandatory safety check. There is no filler, and the purpose is front-loaded.

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, email-sending action with an output schema and full parameter documentation, the description provides the essential decision context: what happens (declines are queued and may send), when it is allowed, and when it must not happen. Nothing crucial 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 coverage is 100%, so the schema already documents each parameter. The description adds a useful semantic layer by tying 'explicitly approved' to the `confirmed` const and referencing the `preference` field ('Depending on the user's preference'), reinforcing how the parameters work together.

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 action ('Queue decline replies') and a clear resource ('recruiter outreach'), and the capitalized 'SENDS email' makes its effect unmistakable. It is conceptually distinct from nearby siblings like inbox.dismiss or inbox.unsubscribe, but does not name any sibling to aid quick differentiation.

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

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

The description provides a crisp precondition: 'Only call after the user explicitly approved declining these specific conversations,' which tells an agent when the tool is appropriate. It does not offer alternatives or explicit negative use-cases, so it stops short of full 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 convey readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description adds a valuable behavioral detail not encoded in the annotations: dismiss also marks the mail read in Gmail. This is consistent with the destructiveHint and does not contradict 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?

One concise sentence that front-loads the purpose and the key side effect. No filler, no repetition of the name or schema, and every word contributes to the agent's understanding.

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 one-parameter tool with a full schema, output schema, and clear annotations, the description is complete. It covers what is dismissed, when to do it, and a notable side effect, leaving no major gap for an agent to call it correctly.

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

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

The only parameter, ids, is already fully described in the schema as 'Inbox item ids to dismiss'. The description's phrase does not add meaningful semantic detail beyond that. With 100% schema coverage, this stays at the baseline.

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

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

The description states a specific verb and resource: 'Dismiss inbox items'. It further clarifies the intended use case with 'you are not acting on', which distinguishes it from sibling tools like inbox.accept or inbox.decline. The parenthetical 'also marks the mail read in Gmail' adds a concrete distinguishing effect.

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 'you are not acting on' gives a clear context for when to use the tool. However, it does not explicitly mention alternatives or conditions for not using it, such as pointing to inbox.mark_read when only marking read is wanted.

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 readOnly/idempotent/non-destructive behavior, so the description's main job is adding context. It usefully reveals that the return format is HTML and that no outbound message is sent, which exceeds the annotations without contradicting them.

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

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

Two short sentences front-load the core action and add only high-value constraints. Every clause earns its place: generate a draft, return HTML, don't send anything.

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 full parameter documentation, an output schema, and annotations that cover safety, the description completes the picture with the key non-obvious behavior: no message is actually sent. An agent has enough to invoke it correctly.

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

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

Schema description coverage is 100%, and both parameters are already well documented—item_id is identified and kind has explicit enum semantics. The description adds no parameter-specific guidance, 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?

The description states a concrete action—generate an AI reply draft—on a specific resource (an inbox item) and clearly frames the result as a draft for review rather than a sent message. This distinguishes it from send/accept/decline tools even without naming them.

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 establishes the right mental model: use this when you want a draft to review, not when you intend to finalize a send. It explicitly says the tool 'does not send anything,' which implicitly excludes inbox.send_reply, but it doesn't explicitly name an 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 declare this as read-only, idempotent, and non-destructive. The description adds useful behavioral context by specifying that the response also includes related job and application data, which is not implied by the annotations alone.

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, front-loaded sentence with no redundant terms. Every word carries information and the core purpose is immediate.

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 single-parameter get operation with a full annotations and an output schema, the description is sufficient. It states what it returns and the relationship scope, leaving nothing critical for an agent to infer.

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 input schema has one parameter, item_id, with a description already explaining what it is. Schema description coverage is 100%, so the description contributes little beyond what the schema provides.

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

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

The description states a specific action ('Get'), a precise resource ('one inbox item'), and a clear scope ('with its related job and application'). This differentiates it from sibling tools like inbox.list and inbox.get_thread, which have different collection/relationship scopes.

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 clearly implies the tool is for fetching a single inbox item along with its related job and application, which helps an agent choose it over listing or thread-focused tools. It does not explicitly name alternatives or exclusions, but the intended use case is evident.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the 'full thread' scope but does not describe other behavioral details; however, with annotations present, the bar is lower.

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 states exactly what the tool does and leaves out irrelevant detail.

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

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

The tool is simple with one required parameter, safe-read annotations, and an output schema available. The description is sufficient for a correct call given these supporting signals.

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 describes item_id as 'Inbox item id' with 100% coverage, so the only parameter is already documented. The description does not add extra meaning beyond that, but none is necessary at this 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?

The description combines a specific verb ('Fetch'), a resource ('full email thread'), and the relation to an inbox item. It distinguishes the tool from single-item getters like inbox.get and inbox.list by emphasizing the full thread.

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 clearly establishes the use case: retrieving a complete thread for an inbox item. It does not explicitly name alternatives or exclusion conditions, but the intent is unambiguous enough to guide 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 cover readOnly/idempotent/destructive safety. The description adds one behavioral qualifier—the list only contains conversations Refine has matched to the user's job search—but does not comment on ordering, pagination, or how the 'low_signal' shelf behaves beyond the schema. It is consistent with the annotations and supplies modest extra context.

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

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

The description is a single early-trigger sentence with no filler; the verb and resource appear first. The wording 'Refine matched' is slightly awkward, which prevents a perfect readability score, but there is no unnecessary 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 5 thoroughly documented parameters, a readOnly annotation set, and an output schema present, the description only needs to supply purpose and scope, which it does with 'Refine matched to your job search' and the category list. It stops short of explaining how a multi-tab listing interchanges with single-thread view, but the structured data already carries much of that burden.

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

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

The input schema describes all five parameters with enums and descriptions, so schema description coverage is 100%. The description merely restates three of the tab category values, adding no extra semantic detail or guidance 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 opens with a concrete verb–resource pair ('List email conversations') and immediately narrows the scope to job-search-matched conversations in applications, interviews, and outreach. This clearly separates the listing role from the get-by-id and mutation siblings, and it is not simply a restatement of 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?

The parenthetical categories establish a clear context: use this to see job-search-related conversations by tab. It does not spell out 'when not to use' or compare to inbox.get/get_thread, but the context is strong enough that an agent can infer the shape of use.

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 establish that the tool is not read-only, is not idempotent, and has open-world behavior; the description concretizes this by saying it checks Gmail now and returns per-account sync status. It adds useful context about the tool's immediate external effect, though it does not discuss rate limits or failure modes.

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

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

The description is a single compact line: it states the action and the return shape in one breath, with no filler or redundant wording. Every phrase 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 no-parameter refresh tool with an output schema and annotations describing its open-world, non-idempotent, non-destructive nature, this one-sentence description provides enough behavioral and return-value context to guide invocation. There is no missing input or complex environment to explain.

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 and the schema covers this fully, so there is nothing additional the description must clarify. The baseline for a zero-parameter tool 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?

Description states a clear verb ('Check') and resource ('Gmail for new mail'), while the 'now' signals an immediate manual sync action. It is easily distinguished from siblings like inbox.list and inbox.get because the emphasis is on refreshing/syncing rather than reading or searching.

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 intention is implied: call this tool to force a Gmail sync right now. However, it does not explicitly explain when to prefer this over related tools such as inbox.status or jobs.refresh, nor does it mention any cases where a manual refresh should be avoided.

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?

Even though destructiveHint is true, the description adds crucial context: this sends an actual email to a real person from the user's Gmail address. It also emphasizes explicit user approval, which is exactly the behavioral disclosure an agent needs before invoking this non-idempotent action.

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 compact and effective: two sentences communicate what the tool does, why it matters, and when it is safe to invoke. There is no irrelevant detail.

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 full input schema, output schema, and annotations indicating a destructive/non-idempotent operation, the description fills the main gap: the real-world consequence and the approval requirement. The tool definition is complete enough for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents item_id, body, confirmed, and draft_kind. The description reinforces that the body must be exactly what the user approved, but it does not add much beyond the schema's existing parameter documentation.

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 action: sending an email reply through the user's Gmail. The explicit mention that it emails a real person from the user's address clearly distinguishes it from drafting or other non-sending inbox operations.

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 strong precondition: only call after the user has seen the exact message body and explicitly approved sending. It doesn't explicitly name an alternative sibling like inbox.draft_reply, but it gives a clear go/no-go gate that prevents premature sends.

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, covering the safety profile. The description adds scope about returned data, but it does not disclose whether the tool can be called without an account connection, whether it blocks, or that it never initiates a sync. This is acceptable given annotation coverage but not highly transparent beyond 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 a single compact sentence that front-loads the service and resource ('Per-account inbox sync status') followed immediately by the three key data points. There is no redundant or marketing language; every phrase 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 read-only status tool with no parameters, an output schema, and complete annotations, the description supplies exactly the needed domain context: accounts, syncing state, last sync time. No additional information is necessary for an agent to decide whether 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?

The tool has zero parameters, so the input schema is fully complete with 100% coverage. There is nothing additional the description needs to clarify; per the baseline for no parameters, the high score 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 defines what the tool returns: per-account inbox sync status, with specific attributes listed (connected accounts, syncing state, last sync time). This distinguishes it from sibling inbox operations like inbox.get, inbox.list, and inbox.refresh, which deal with message content or syncing actions rather than status.

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 parenthetical fields imply this is for checking sync health/connectivity rather than reading or refreshing messages. However, there is no explicit when-to-use guidance, no alternatives named, and no exclusions such as 'does not trigger a refresh' or 'use inbox.refresh to initiate sync'.

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 mark the operation as destructive, but the description goes further by warning that the undo can delete a board record the automatic action created. This is exactly the kind of concrete behavioral context that adds value beyond structured metadata.

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, no filler, with the crucial side-effect warning placed first. It is compact, readable, and every word adds 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?

Given the simple input schema, the presence of an output schema, and the annotations, this description is sufficient. The only minor gap is that it does not spell out exactly when the board record deletion occurs, though the wording still conveys the risk clearly.

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 provides 100% coverage for the single required parameter item_id with the description 'Inbox item id'. The tool description itself adds no additional parameter-specific detail, so 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 a specific verb, resource, and consequence: 'Undo an auto-applied inbox action' and 'can delete a board record'. This distinguishes it from other inbox.* sibling tools and is not a mere restatement of the title.

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 'auto-applied' qualifier gives clear context: this tool is for undoing automatic inbox actions, not manual ones. It doesn't explicitly list alternatives or when-not-to-use, but the intended situation is clear and unaffected by ambiguity.

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 mark the tool as destructive, but the description adds vital context: it changes the user's real email subscriptions, requires confirmation, and acts specifically via one-click list-unsubscribe. This goes well beyond the structured hints and explains the real-world consequence of calling 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?

The description is two compact sentences with no filler. The action and its consequence are front-loaded, and the usage distinction is stated immediately after.

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 nature, the online available output schema, and clear parameter schema, the description covers the essential guidance: what happens, when to use it, when not to use it, and what to confirm with the user. Nothing critical is missing.

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

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

The schema already documents 'item_id' fully with a clear description ('Inbox item id'), so schema coverage is 100%. The tool description does not add parameter-specific detail, but the single required parameter is already well-documented by the schema, so 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 states a specific verb ('Unsubscribe') on a specific resource (the user's sender mailing list) and names the mechanism ('one-click list-unsubscribe'). It also differentiates from the 'decline' sibling by noting this is for bulk senders, not individuals.

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 guidance: use for unwanted bulk senders, not for a person you can simply decline, and confirm with the user before calling. This clearly routes the agent between inbox.unsubscribe, inbox.decline, and related inbox actions.

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 behavioral details beyond annotations: the flow is browser-based, is non-interactive on Refine's side, and the connected Gmail account becomes linked to the Refine account. Annotations already indicate it is not read-only and has open-world effects; the description enriches this with the user-side flow.

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

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

Three compact sentences, each adding distinct value: purpose, browser-flow detail, and security requirement. No fluff 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?

The description fully explains what the tool does, the security caveat, and the flow involved, with no parameters to document and an output schema present. An agent can safely call this tool on the basis of the description alone.

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 there are no parameter semantics to clarify. The description's role here is reduced, but it still explains the intended field to fill in the 'link' outcome. A baseline of 4 for no-parameter tools 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 a link for the user to connect a Gmail account to Refine.' It clearly differentiates from sibling tools like integrations.list or inbox operations by focusing on the one-time OAuth connection flow.

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 important usage context: the connection happens in the browser, no Refine sign-in is needed, and the link must only be shared with the account owner. It does not explicitly contrast against alternatives, but the tool's scope is unambiguous.

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

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

Annotations already carry readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read. The description adds behavioral context by stating that the result is connected Google accounts and their grant status, which goes beyond what annotations encode. No contradictions, and there is room to describe the exact status values or response shape, but the description is adequate for an idempotent list call when output schema is present.

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

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

Two sentences with no filler: the first states exactly what the tool does, the second provides the relevant alternative action. The core meaning is front-loaded, and every word contributes. This is an ideal brevity-to-information ratio.

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

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

For a zero-argument listing tool with an existing output schema and strong safety annotations, the description is complete. It specifies the resource (connected Google accounts), the aspect (grant status), and the adjacent action (connect). There is nothing an agent needs to call it correctly that the description omits.

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 0 parameters, so there is no parameter semantics to describe. The schema description coverage is 100% (vacuously true with an empty properties object), and the description correctly contains no parameter details because none exist. A 4 is appropriate because the zero-parameter case removes the need for explanation, and the description focuses correctly on resource and 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?

The description uses a specific verb ('List') and resource ('connected Google accounts'), and adds 'grant status' as scope, differentiating it from the other list tools in its sibling set. It also explicitly names the complementary action (integrations.connect_google) for extending state. There is no ambiguity about what this tool returns.

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

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

The description gives an explicit usage signal: to connect a new account, use integrations.connect_google. This clearly routes the agent away from the list tool when its purpose is creation, and by saying 'connected Google accounts' it implies reading is the intended use. This is stronger than most tool definitions because it names the alternative directly.

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 communicate that this is not read-only and is not idempotent, so the description does not need to restate that. The phrase 'for a job' adds useful context that interview records are scoped to a job, but it does not detail any side effects, required job existence, or subsequent 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, compact sentence with no filler words. It front-loads the core action and resource, and every word contributes to the meaning.

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

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

With full parameter coverage, an output schema, and annotations, the description is minimally workable for a straightforward add tool. However, it lacks explicit guidance about existing jobs, alternatives such as interviews.update, or any need to confirm that the interview is a new record rather than a modification.

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 already has a meaningful description in the schema. The tool description itself adds no additional parameter-level detail, which means the schema is doing the necessary work.

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, 'Log', plus the object 'an interview' and the scope 'for a job,' so the agent can tell this creates an interview record. It does not explicitly contrast with sibling tools like interviews.update or interviews.delete, but its additive intent is fairly clear from the context.

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

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

The description gives no guidance about when to use this tool versus alternatives. It does not mention that this is for creating a new interview, while interviews.update would be for modifying an existing one, nor does it call out prerequisites such as needing an existing job_id.

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 indicate destructive and non-readOnly behavior. The description adds meaningful procedural context by saying 'permanently', 'confirm with the user first', and 'it cannot be undone', which goes beyond the structured annotations and tells the agent how to handle safety.

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 with no padding. The action is stated first, and the safety warning is front-loaded immediately after, making it easy for an agent to consume.

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 delete tool, the description fully covers the essential contextual factors: what is deleted, that it is permanent, that user confirmation is required, and that it is undoable. The output schema also exists, freeing the description from needing 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?

Both parameters are fully described in the input schema with 100% coverage. The description itself does not add additional meaning beyond referencing 'a job', so it meets the baseline but does not enhance parameter understanding.

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

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

The description clearly states a specific verb and resource: permanently delete an interview from a job. This effectively distinguishes it from sibling tools like interviews.update, interviews.list, and jobs.delete without ambiguity.

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

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

The description gives a clear, actionable usage condition: confirm with the user first. It also warns against casual use by emphasizing that deletion cannot be undone. It does not explicitly enumerate when to use this over alternatives, but the destructive scope is clear enough.

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 safe-read behavior is covered. The description adds the job-scoping detail but provides no further behavioral context such as pagination or permission requirements. That is acceptable given the strong annotation coverage.

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

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

The description is a single focused sentence with no filler. It states the action, resource, and scope efficiently.

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 such a simple list operation, the description plus annotations and output schema are sufficient. The required job_id is specified, the operation is known to be read-only and idempotent, and the output schema covers return structure.

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 documents job_id as a required string, and schema description coverage is 100%. The description reinforces that the job context is needed but adds no additional meaning beyond the schema.

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

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

The description is specific: it names the verb (list), the resource (interviews), and the scope (all interviews for a job). This clearly distinguishes it from sibling tools like interviews.add, interviews.delete, and interviews.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 makes the intended context clear: listing interviews associated with a job identified by job_id. It does not explicitly name alternatives or say when not to use the tool, but the purpose is unambiguous enough for an agent to select it correctly.

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, so the safety profile is covered by structured data rather than the description. The description itself adds no behavioral context, such as whether unspecified fields are unchanged or overwritten, or whether partial updates are allowed.

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 only one sentence with no filler and is front-loaded with the action and target. It is concise and easy to scan, though it is so minimal that it contributes little beyond restating the tool's purpose.

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 rich schema, output schema, and annotations carry most of the informational weight, making the tool callable. However, the description still leaves gaps around important context such as whether updates are partial or full, which fields can be changed together, and how required fields like job_id are used for scoping.

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

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

Schema description coverage is 100%, so every parameter is already meaningfully described in the input schema. The tool description does not add any additional parameter-level meaning, making the baseline of 3 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 ('Update') and resource ('existing interview'), which clearly distinguishes the operation from siblings like interviews.add, interviews.delete, and interviews.list. However, it does not explicitly call out those alternatives or mention the updatable fields, so it stops short of full sibling differentiation.

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

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

The description provides no guidance on when to use this tool instead of another. It neither names alternatives such as interviews.add or interviews.delete nor explains that an existing interview must already exist, so the agent must infer usage entirely 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 supply the safety profile (readOnlyHint: false, destructiveHint: false, idempotentHint: false), and the description adds no behavioral context beyond that. It says nothing about duplicates on repeated calls, the meaning of 'job scrape state', or openWorld side effects, leaving the agent to infer everything from the 'add' verb.

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 action is immediate and scannable. It is appropriately brief, though the brevity borders on under-specification, a cost already accounted for in other dimensions.

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?

Between the 100% schema descriptions, output schema, and annotations, most structural information is present. What is missing is context: the meaning of 'journey', how to handle a duplicate posting given idempotentHint: false, and any guidance connecting the optional parameters to the common use. A little additional scope would make the description genuinely self-sufficient.

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

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

Schema description coverage is 100%, so title, company, url, state, location, journey_id, and the rest are already documented structurally. The description adds little — the only overlap is 'journey' loosely mapping to journey_id, and it doesn't clarify which parameters matter or when optional ones should be supplied.

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

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

The description clearly identifies the action (add) and resource (a new job), making the create operation obvious against sibling tools like jobs.update, jobs.archive, and jobs.mark_applied. The phrase 'to your journey' adds application context but doesn't explicitly disclaim use cases like updating an existing job, so it stops just short of full sibling differentiation.

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

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

There is no guidance on when to call this tool versus jobs.update, jobs.mark_applied, or jobs.archive. An agent cannot determine whether the correct action is to add a new job or update/revive an existing one; no alternatives, prerequisites, or exclusions 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?

The parenthetical 'close/reject' adds semantic context beyond the annotations, indicating the action is a state transition rather than a hidden or soft removal. The annotations already provide idempotent and non-destructive hints, and the description does not contradict them, but it doesn't disclose additional side effects or reversibility.

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, focused sentence; every word adds value. The parenthetical improves clarity without adding unnecessary length.

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

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

For a single-parameter state-change tool with an output schema and adequate annotations, the description is mostly complete. Missing is a note about reversibility or pointing to jobs.unarchive as the opposite, but this is a minor gap given the context.

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

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

The input schema has 100% coverage for the single parameter job_id, and the description adds no extra detail about the parameter. With full schema coverage, the baseline of 3 applies without the description needing to compensate.

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

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

The description uses a specific verb and resource ('Archive a job') plus a clarifying parenthetical ('close/reject') that disambiguates the intended meaning. It is clear and concise, though it doesn't explicitly call out any sibling tool to draw a comparison.

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 no guidance on when to use this tool versus alternatives such as jobs.delete or jobs.unarchive. It states what the tool does but not the conditions, prerequisites, or context that would select it over siblings.

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

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

Beyond the annotations' destructiveHint, the description discloses the permanence ('cannot be undone'), the requirement for user confirmation, and the fact that the application is also deleted. This meaningfully extends the annotation-provided safety signal.

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, no wasted words. The destructive action is front-loaded, the confirmation requirement follows, and the alternative tool sentence concludes efficiently. Every sentence carries vital operational 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?

Given the single parameter, sufficient annotations, and the description's warnings and alternative routing, the definition is complete for an agent to select and invoke this tool 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?

There is only one parameter, job_id, and the schema describes it as 'Job id' with 100% coverage. The description adds no new parameter semantics beyond the schema, so the appropriate baseline is 3.

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 ('Permanently delete'), a resource ('a job and its application from the board'), and clearly differentiates from the sibling jobs.archive with a contrasting use case. This leaves no doubt about what the tool does.

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

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

Explicitly instructs when to use: only after confirming with the user, and when the job truly must be removed. It also names the alternative jobs.archive for less final cases. This provides direct 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 the 'specific job' scope but does not describe any additional behavioral nuances, which is acceptable for a simple read-only single-entity endpoint.

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 one short, front-loaded sentence with no filler. It earns its place while still being scannable.

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

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

For a single-parameter, read-only getter, the annotations and output schema cover most operational needs. The one missing piece is an explicit routing note distinguishing jobs.get from jobs.list, though the 'specific job' phrasing makes the intent fairly 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?

The schema provides 100% coverage: job_id is a required string with description 'Job id'. The description says 'specific job', which maps naturally to job_id, but adds no extra semantic 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?

The description clearly states the action ('Get') and the resource ('details of a specific job'). The word 'specific' helps distinguish this from jobs.list and the other jobs.* 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?

The 'specific job' wording implies this is for retrieving a known single job by ID, but it never explicitly says when to prefer it over jobs.list or what to do when only partial lookup info is available. Usage context is implied, not 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?

The annotations already declare readOnlyHint, idempotentHint, a false destructiveHint, and closed-world behavior. The description adds only the 'in your journey' scoping and does not describe pagination behavior or return details, though the output schema and parameter schema help compensate.

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 one concise, front-loaded sentence with no wasted words. 'In your journey' adds a meaningful scoping qualifier without bloating the 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, read-only list tool with no required parameters, fully documented optional pagination, and an output schema, the definition provides enough information for an agent to invoke it correctly. The missing guidance about sibling tools is already reflected in the usage dimension.

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 page and limit are already documented, including the pagination cursor semantics and the maximum limit. The description adds no additional parameter context, 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 action ('list') and resource ('jobs'), and adds useful scope with 'in your journey.' It clearly communicates the tool's basic purpose, though it does not explicitly distinguish itself from related siblings like jobs.get 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 description gives no when-to-use or when-not-to-use guidance, and it does not name alternatives. An agent can infer that this tool is for listing jobs, but it is not told when to prefer jobs.list over jobs.refresh, jobs.get, or signals.list_applied_jobs.

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 indicate a mutating, idempotent operation (readOnlyHint=false, destructiveHint=true, idempotentHint=true), and the description aligns with those without adding anything beyond 'applied'. It does not mention side effects, what changes, or whether prior status is overwritten.

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 short, direct sentence with no filler. It front-loads the action and target, though it is somewhat terse and could include a bit more operational context without becoming redundant.

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

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

For a simple one-parameter tool with an output schema and meaningful annotations, this is minimally viable. However, the description omits when to reach for this tool over sibling job tools and does not say what observable effect 'mark as applied' produces.

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 fully documents the only parameter, job_id, as 'Job id'. The description adds no extra meaning about how this parameter participates in the operation, so the baseline of 3 is appropriate.

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

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

The description names the action ('mark') and resource ('a job as applied') clearly, so an agent can tell this is a status transition rather than a generic update. It distinguishes implicitly from siblings like jobs.archive and jobs.delete, but it doesn't explicitly clarify what 'applied' means or who it applies to.

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 given about when to use this tool versus alternatives such as jobs.update, jobs.add, or signals.list_applied_jobs. The description only states what the tool does, not when it should be chosen or when it should not be used.

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

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

The description discloses that the tool performs an external re-scrape and refreshes stored details, which adds informative context beyond the annotations. It does not describe side effects such as which fields may change, rate limits, or whether stale data is replaced.

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

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

The description is a single concise sentence that front-loads the action and clearly states the purpose. There is no wasted wording or redundancy.

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

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

For a single-required-parameter tool with an output schema and annotations, the description is essentially complete: an agent knows what the tool does and what identifier to supply. It could further clarify prerequisites, such as whether the job must already exist, but this is a minor gap given the tool's simplicity.

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 input schema fully documents the only parameter, job_id, as 'Job id', so the description does not need to add much. It provides no additional semantic detail beyond what the schema already covers, which is acceptable given 100% schema description 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 (re-scrape) and resource (a job posting), with the outcome of refreshing its details. This is clear and distinct from a plain get or update, though it does not explicitly name a sibling it is not.

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 intended use is implied: use this tool when you want to refresh a job's details by re-scraping the posting. However, it offers no explicit guidance about when to choose it over alternatives like jobs.get or jobs.update.

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 meaning beyond the annotations by specifying the actual behavior: moving a job from archived state back to active board. It does not describe edge cases like restoring an already-active job, but the idempotentHint and destructiveHint annotations already cover repeatability and non-destructiveness.

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 entire description is one concise sentence that communicates the action, the resource, and the result with no filler. It is front-loaded and every word 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 single-parameter mutation with a clear output schema, complete annotations, and an obvious sibling counterpart, the description is fully sufficient. Nothing critical about how or when to invoke the tool is missing.

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

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

The only parameter, job_id, already has 100% schema description coverage, so the schema fully explains what is needed. The description does not add parameter-level detail, but with a single well-defined parameter and a clear schema, 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 uses a specific verb, 'Restore', a clear resource ('an archived job'), and a clear end state ('active board'). This unambiguously distinguishes it from sibling tools like jobs.archive and 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 description clearly indicates that this tool is for archived jobs that need to be returned to the active board, which is a clear context and directly contrasts with jobs.archive. It does not explicitly list alternatives or when-not-to-use cases, but the scope is clear enough from the wording and siblings.

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 provide the behavioral profile: readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description adds minimal behavior beyond the verb itself, such as clarifying whether the update is partial or full, but it does not contradict the annotations and the 'in your journey' adds a small context. Since a neutral description on top of annotations is acceptable, this is a 3.

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 concise sentence with no fluff. The verb and resource are front-loaded, and the phrase 'in your journey' is the only extra context, which is still economical. This is appropriately sized for a tool whose details are largely carried by the schema and 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?

Given the 12 parameters, sibling mutations, and an output schema, the description is barely sufficient. It does not mention update semantics (patch vs replace) or how it relates to jobs.update_notes, but the schema and annotations fill many gaps, so the description remains minimally viable rather than clearly complete.

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

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

Schema coverage is 100% — every parameter has a description. The tool description adds no extra semantic meaning to parameters, so it does not go beyond what structured fields already provide. The baseline 3 is appropriate.

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

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

The description clearly states the action ('update'), the resource ('a job'), and the context ('in your journey'), which is a specific and meaningful scope. It distinguishes the tool from non-update actions like add/archive/delete/list, but it does not explicitly differentiate from the sibling jobs.update_notes or provide a scoping constraint that separates them.

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. The description does not mention jobs.update_notes, jobs.mark_applied, or any conditions for choosing this update over others, leaving the agent to infer usage from the name and schema 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 indicate destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds no detail about whether notes are replaced wholesale, permissions required, or side effects such as overwriting previous notes. It is consistent with the annotations, so no contradiction.

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

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

The description is a single, concise sentence that immediately communicates the action and resource. Every word earns its place, and there is no clutter.

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

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

For a two-parameter tool with full schema coverage, an output schema, and annotations that convey safety, a short description is sufficient. The only slight gap is the lack of usage guidance, but the tool is simple enough that the key details are covered elsewhere.

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 notes are already documented. The description only says that notes on a job are updated, which adds little beyond what the schema already defines, but it is consistent.

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 and resource: 'Update notes on a job.' It distinguishes itself from sibling jobs.update by focusing specifically on notes, though it does not explicitly name or contrast with that sibling.

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

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

There is no guidance about when to use this tool versus alternatives such as jobs.update or how the update interacts with existing note content. The description only implies a narrow use case, but provides no exclusions or alternative routing.

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

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

Annotations already provide readOnlyHint: false, destructiveHint: true, and idempotentHint: true, so the description does not need to restate that this is a mutation. The description adds minimal behavioral context by naming the mutable fields, but does not explain what happens to existing settings when only some fields are provided or whether the update fully replaces the previous settings value.

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 front-loaded sentence with no repetition, no filler, and a clear parenthetical list of the affected fields. It is easy to parse quickly and contains no irrelevant details.

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 update tool with 3 optional string parameters, the schema and description are largely sufficient. The operation has an output schema and many safety cues already captured in annotations. However, it does not explicitly explain whether all fields are overwritten independently or if updating is a partial patch, which would help an agent understand user intent more precisely.

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, with each parameter having a clear explanation: name, industry, and what optimization goal means. The tool description only repeats these property names and does not add extra meaning about formats, value constraints, defaults, or optionality.

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 says 'Update your journey settings' and explicitly lists the editable fields: name, industry, and optimization goal. This identifies both the verb and the resource without ambiguity, and the 'journey' prefix separates it clearly from update tools in other domains like jobs.update or offers.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 gives an obvious trigger scenario: use when you need to change the user's journey name, industry, or optimization goal. No alternative journey-related tool exists among the siblings, so explicit 'when-not-to-use' guidance is not necessary, though a bit more context about prerequisites or whether fields are optional would improve 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=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds meaningful behavioral context by clarifying the list is scoped to signal notifications for tracked companies, which is not obvious purely from the parameter names.

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 one sentence consisting of a direct verb-object pair followed by a clarifying parenthetical. It is tightly executive, front-loaded, and contains no redundant or filler language.

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 moderate complexity (8 documented parameters, 100% schema coverage, and an output schema), the description is sufficient to define the purpose and scope. It does not need to cover return format or pagination because those are available in the output schema, so nothing essential is omitted.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters. The description adds a slight conceptual context by defining 'signal notifications' as new openings, but it does not expand on the parameters' 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 uses a specific verb 'List' and a clear resource 'signal notifications', with a parenthetical defining them as 'new openings at tracked companies'. This distinguishes the listing action from sibling notification actions like notifications.read and notifications.read_all.

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 clearly explains what the tool does but does not provide explicit context about when to use it over alternatives or when to avoid it. The intended usage is implied from the name and parenthetical, but there is no mention of sibling tools or a 'if you need X, use Y' clause.

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 clearly indicates a state-changing action, and annotations already disclose that it is idempotent and not destructive. No additional behavioral context such as already-read behavior or permissions is provided, but the annotations cover the essential safety profile.

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

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

The description is a single concise sentence with no filler. Every word supports the meaning, and the core behavior is front-loaded.

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 simple one-parameter, idempotent mutation with a full input schema and an output schema. The description is sufficient for an agent to call it correctly, though a tiny bit more context about already-read behavior would be a nice enhancement.

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

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

Schema description coverage is 100%, and the single required parameter notification_id is already well documented in the schema. The description does not need to add much parameter detail, so it appropriately stays at the baseline.

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

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

The description states a specific verb and resource: mark a notification as read. The word 'one' clearly distinguishes it from batch operations like notifications.read_all.

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 singular 'one notification' implies this tool is for single-target reads and not for marking multiple notifications. However, it does not explicitly say when to prefer notifications.read_all or when this tool is not appropriate.

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 is consistent with annotations and does not contradict them. It adds the important scope 'all,' beyond what the bare annotations state, but it does not disclose additional behavioral details such as whether unread-only notifications are affected, whether it affects all notification types, or how the result is returned.

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 no filler. Every word earns its place, and the key action 'Mark all read' is front-loaded. It is as concise as possible for a zero-parameter 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?

For a zero-parameter mutation with idempotent and non-destructive hints and an output schema, this description is sufficiently complete. An agent needs no further contextual details to invoke the call correctly, though it could benefit from a note about filters or scoping.

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 there is no parameter meaning to clarify. The description fully covers the call semantics because there is no way to customize its invocation. The schema description coverage is 100% with no parameters.

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

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

The description uses a specific verb and resource: 'Mark all notifications as read.' The word 'all' explicitly differentiates it from siblings like notifications.read and inbox.mark_read. The tool's scope is immediately clear without needing to open 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 description implies the correct use case—marking the entire notification set as read—but does not say when not to use it or point to alternatives like notifications.read or inbox.mark_read for more targeted operations. No exclusions or decision rules are provided.

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

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

Beyond the annotations, the description adds meaningful behavioral context: it closes out the search for the role, requires explicit user confirmation, and does not email the employer. These details materially reduce surprise for an agent invoking a destructive, non-read-only 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?

The description is concise and front-loaded: it states the action first, then the most important side effect, then the confirmation requirement, then a non-effect. Every sentence adds useful information and there is no filler.

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

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

For a single-parameter mutation tool with output schema and annotations present, the description covers everything an agent needs before calling: the purpose, the irreversible-like consequence, the need for confirmation, and a relevant non-effect. 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 documents job_id fully with 100% description coverage, so the description does not need to repeat parameter meanings. The phrase 'for a job' loosely aligns with job_id, but it does not add meaningful parameter semantics beyond what the schema provides.

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

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

The description states a specific verb ('Accept') and a clear resource ('the offer for a job'), and immediately gives the distinguishing consequence: it closes out the search for the role. This makes it easy to differentiate from sibling tools like offers.decline, offers.update, inbox.accept, and inbox.decline without inspecting schemas.

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

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

The description gives explicit usage guidance: this is a major state change that should only happen after user confirmation, and it warns that the action closes out the search. It does not explicitly compare against alternatives like offers.decline or inbox.accept, but the context it provides is enough for an agent to avoid using it prematurely.

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 convey the non-read-only and non-idempotent nature. The description adds mild behavioral context by labeling the action as 'log', implying an activity-event record, but it does not explain side effects such as whether an existing offer is modified, whether this appends to offer history, or whether event_date defaults to today.

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 one concise sentence, starts with the action verb, and includes helpful illustrative event types. Every part contributes to understanding what the tool does, with no fluff or redundant 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?

Given a full parameter schema and output schema, the basic parameters and return format are covered. However, the description lacks critical usage context, especially how this logging tool relates to other offer updates and what side effects occur on the offer itself. It is functional but not fully self-sufficient for an agent deciding between offers.add_negotiation and offers.update.

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 explains all seven parameters. The description adds no additional meaning about salary_cents, bonus_cents, equity_text, event_date, or how they relate to the negotiation event. Because coverage is complete, 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 uses a specific verb and resource: 'Log a negotiation event on an offer.' It makes clear the tool records a negotiation event rather than creating or updating the offer itself. However, it does not explicitly differentiate from closely related siblings like offers.update or offers.delete_negotiation, so the clarity is good but not perfect.

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

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

The description gives no guidance about when to use this tool versus alternatives such as offers.update, offers.create, or offers.delete_negotiation. It states what the tool does but not when it is the right choice or when it is not.

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 indicate this is a mutating action (readOnlyHint=false), and the description adds little beyond the word 'Record.' It does not mention whether an existing offer is overwritten, what happens on duplicate calls, permissions needed, or what meaningful objects are affected. It does not contradict the annotations, but it also does not disclose anything beyond 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 one short sentence with no filler, front-loaded with the core action and object. Every word contributes value, and it is appropriately sized for a straightforward create operation.

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 minimal but the schema is rich and fully documented, so the agent has enough raw context to understand inputs. However, there is no context around when to create versus updating an offer or adding negotiation details. For a tool with 17 parameters, a little more framing would help, though the output schema lowers the burden of explaining 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%, so the description does not need to document every parameter. The phrase 'with compensation details' summarizes the parameter group well, but it adds no meaning beyond the schema, where fields like base_salary_cents and bonus_cents are already clearly described.

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 and resource: 'Record a job offer with compensation details.' It is understandable and consistent with the tool name offers.create. However, it does not explicitly differentiate itself from sibling tools like offers.update or offers.add_negotiation.

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

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

The description gives no guidance on when to use this tool versus alternatives such as offers.update or offers.add_negotiation. There is no mention of coverage for new offers, existing offers, or negotiation scenarios. The intended usage must be inferred from the tool name rather than described.

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 indicate destructiveHint=true and readOnlyHint=false, and the description reinforces those by calling it a 'major state change' and requiring user confirmation. It adds a meaningful side-effect exclusion by noting it does not email the employer. It does not fully describe all consequences, but the annotation plus description provide solid transparency.

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?

Very concise and front-loaded: the action, the importance, and a boundary are each covered in two sentences. Slightly more could be said about reversibility or confirmation mechanics, but the definition wastes no words.

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

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

For a one-parameter mutation with annotations and an output schema, the description is mostly complete: it says what the tool does, flags a major state change, mandates user confirmation, and notes a common misconception. It does not mention what happens after declining or whether the action is reversible, but those are less critical given the annotations.

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

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

Schema description coverage is 100% and the sole parameter job_id is already described as 'Job id'. The description adds no additional parameter-level meaning, 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?

States a specific verb and resource ('Decline the offer for a job') and adds key semantic context that it is a major state change, which helps distinguish it from mere dismissal or read operations. The phrase 'does not email the employer' further disambiguates the expected behavior.

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

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

Explicitly instructs to 'confirm with the user first', giving important usage guidance. It also states what the tool does not do ('does not email the employer'), which is a useful exclusion, though it does not explicitly name alternative sibling tools or provide when-not-to-use conditions beyond that.

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 mark destructiveHint=true and readOnlyHint=false, or 'implemented'. The description adds valuable context beyond those annotations: the operation is permanent, cannot be undone, requires user confirmation, and does not delete the associated job. These are behavioral facts the annotations do not cover, and there is no contradiction with 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 sentences with no filler: the first states the action and scope, the second gives strict usage guidance. Every word contributes to safe and correct invocation. Information is front-loaded and immediately usable.

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

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

Given a single documented parameter, a clear output schema, and annotations describing safety, the description is complete. It covers the consequence ('permanently delete'), the boundary ('the job stays'), the necessity of a user confirmation, and the irreversible nature. Nothing relevant 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 sole parameter job_id is already documented in the schema with description 'Job id', and schema coverage is 100%. The description adds no new meaning to the parameter itself, only contextualizes the operation on the offer for that job, which is sufficient. Baseline 3 is appropriate because the schema carries the weight.

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 and resource: 'Permanently delete the offer recorded for a job'. It also clarifies the job stays, which distinguishes this from deleting the job itself or from offers.delete_negotiation. The purpose is unmistakable even though the title is null.

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

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

The description gives clear conditions for use: 'Use only to fix a mistake' and 'confirm with the user first'. It doesn't explicitly name alternative tools, but the scoping ('the job stays') and the irreversibility warning provide enough context for an agent to decide when this is and isn't appropriate.

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 consistently describes a destructive action, matching annotations with destructiveHint=true and idempotentHint=true. It also adds that the event is removed from an offer, but does not explain side effects beyond the deletion, such as whether the surrounding offer remains unchanged or how deletion is represented in existing offer data. The annotations cover the key safety characteristics, so no contradiction is present.

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, front-loaded sentence with no filler. It states the action and the object of the action efficiently without repeating the tool name 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?

For a straightforward, two-parameter destructive operation, the description is substantially complete: it identifies the action, the target object, and the offer scoping. The annotations and output schema cover the remaining expectations, such as destructive behavior and return data format, so the description does not need to replicate those details.

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 input schema already provides 100% description coverage for job_id and event_id. The description adds the semantic relationship that the negotiation event is removed from an offer, which slightly clarifies the role of job_id, but it does not add new parameter-level guidance beyond what the schema supplies.

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+resource pair: 'Remove a negotiation event from an offer.' This clearly distinguishes the tool from sibling offers.delete, which removes an entire offer, and offers.add_negotiation, which creates a negotiation event.

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 intended usage is implied by the description: use this tool when you need to remove a negotiation event associated with a specific offer. However, it does not explicitly state when not to use it or mention alternative tools such as offers.delete for deleting the whole offer.

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 covered. The description adds minimal behavioral context beyond scoping the offer to a job, and there is no contradiction with 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 a single, readable sentence with no filler or repetition. It front-loads the action and the resource without wasting the reader's attention.

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-only retrieval tool with an output schema and strong annotations, the description covers what is needed. It could mention what happens when no offer is recorded, but that is not essential for selecting or invoking the 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 job_id already has a description, so the baseline is 3. The description adds only that the offer is scoped to a job, which is consistent with the parameter meaning but does not add substantial new semantics.

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

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

The description uses a specific verb and resource: 'Get the offer recorded for a job'. This clearly targets the offer entity scoped to a job, and distinguishes it from offer-mutating siblings like offers.create, offers.update, and offers.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 description conveys what the tool retrieves, but does not explicitly explain when to choose it over related tools such as jobs.get or offers.accept. Usage is implied by the read-only 'get' phrasing rather than explicitly 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 disclose this is a mutating and potentially destructive action, so the description does not need to repeat that. The description adds little behavioral context beyond saying the offer is updated. No contradiction with annotations is present, so the baseline credit applies.

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 concise sentence that front-loads the verb and object. It contains no filler or repeated title information and is appropriately sized given the rich schema and 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?

The schema, annotations, and output schema supply most needed context. However, the description leaves important update semantics unspecified, such as whether omitted fields are left unchanged or overwritten, and what the effect of the destructive flag is in practice.

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%, meaning the schema already documents all 17 parameters. The description adds no parameter-specific meaning, so the baseline score of 3 for full schema coverage 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: 'Update the offer recorded for a job.' This clearly differentiates it from related offers tools like create, get, accept, decline, and delete, and identifies the domain as job-linked offers.

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

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

The description gives no explicit when-to-use guidance, prerequisites, or exclusions. It does not mention alternatives such as offers.create or offers.get, so the agent must infer when to use this update over similar operations based only on the name and context.

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

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

Annotations already cover the mutation profile (readOnlyHint false, destructiveHint false, idempotentHint true). The description adds that the action is about labeling an inferred trait as accurate, but it does not clarify side effects such as whether the trait becomes permanently confirmed, whether it is a state transition, or what happens to conflicting traits.

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 language. The action, resource, and context ('inferred', 'accurate') are all front-loaded and immediately parseable.

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

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

For a single-parameter tool with annotations and an output schema, the description covers the essential operation with little missing. Its main gap is the absence of explicit routing to persona.correct_trait or persona.remove_trait, but this is a minor completeness concern.

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

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

Schema coverage is 100%, so the schema already documents trait_id. The description does not add clarifications about what format or identifier to use, and there is a mild ambiguity between the parameter name trait_id and its schema description 'Persona trait name'.

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 action ('confirm') applied to a specific resource ('an inferred persona trait') and clarifies the intent ('as accurate'). It is distinct from get and remove, but it does not explicitly distinguish itself from the closely related persona.correct_trait sibling.

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

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

The phrase 'inferred persona trait' implies this tool should be used when a trait has been inferred and the agent accepts it as accurate. However, it provides no explicit guidance about when to use confirm_trait instead of correct_trait or remove_trait.

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 destructiveHint=true and readOnlyHint=false, so the mutating/destructive nature is known. The description adds little behavioral detail beyond that—there's no explanation of whether the trait is overwritten or how the correction is persisted, but given the annotations, a score of 3 is adequate.

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 with no filler. The action and the trigger ('correct ... user says is wrong') are both clearly present, making it easy to scan.

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

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

Given the rich annotations, full parameter description in the schema, and an output schema, the description does not need to explain return values or basic parameter details. The only meaningful omission is the lack of direct sibling differentiation (e.g., confirming vs. correcting vs. removing a trait), but invocation is still straightforward with the tools provided.

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 this dimension defaults to the baseline. The description doesn't add more context about which value field (value_text vs. value_number) should be used, but all parameter details are already clearly documented 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 clearly names the action ('Correct') and the resource ('a persona trait'), and even adds a trigger context ('the user says is wrong'). However, it does not directly differentiate from the sibling tool `persona.confirm_trait` or `persona.remove_trait`, which leaves the agent to infer the distinction from naming alone.

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

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

The phrase 'the user says is wrong' is an explicit use-case trigger: use this tool when a user indicates a known trait is incorrect. It doesn't mention any alternatives or exclusion conditions, so it falls short of the full 'use X instead' 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 that the tool is read-only, idempotent, and non-destructive, so the safety profile is clear. The description adds light value by noting the persona is 'inferred' and includes an understanding score, but it does not disclose further behavioral details beyond what the annotations and output schema would provide.

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

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

Two short sentences deliver purpose, content, and usage guidance with no filler. The core statement is front-loaded and every word contributes meaning.

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

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

For a zero-parameter, read-only lookup tool with an output schema available, the description provides sufficient guidance on what the tool does and how the result should be used. Nothing important is missing for an agent to invoke it correctly.

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

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

The tool has zero parameters and the input schema is empty, so there are no parameter semantics to explain. The baseline for a zero-parameter tool is 4, and the description does not need to compensate for any schema gaps.

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 ('Get') with a clear resource ('the user's persona') and explains what the persona consists of: inferred job-search preferences and traits with an understanding score. This makes the tool's purpose immediately recognizable and naturally distinct from sibling tools like persona.confirm_trait or persona.correct_trait.

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

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

The description gives clear usage context by saying 'Use it to tailor advice and searches,' which tells the agent when the resulting persona data should be applied. It does not explicitly mention alternatives or when not to use it, but the intended call context is evident enough.

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 tool destructive and idempotent, so the description has little additional burden. The phrase 'entirely' slightly reinforces the scope of deletion, but the description does not disclose consequences such as irreversibility or whether associated data is also removed.

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 clear sentence with no unnecessary words. It is efficiently front-loaded with the action and object, making it easy for an agent to parse quickly.

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 one-parameter destructive tool, the description plus annotations and output schema are almost entirely sufficient. Everything essential is present, though a brief note about irreversibility or side effects would make it fully complete.

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

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

The only parameter, trait_id, is documented in the schema as 'Persona trait id', and schema description coverage is 100%. The description does not add any further 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 uses a specific verb and resource: 'Remove a persona trait entirely'. It clearly states the action and object, and the word 'entirely' adds meaningful scope, distinguishing it from other persona-related tools like correct_trait.

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 when-to-use guidance is provided, nor any reference to alternatives. It does not mention when to use remove_trait versus correcting or confirming a trait, leaving the agent to infer the appropriate context from the tool 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 declare readOnlyHint=false and idempotentHint=true. The description adds useful behavioral context: the action both dismisses the current company and blocks it from future recommendations, which goes beyond what the annotations say. It doesn't contradict the annotations and provides a meaningful extra behavior detail.

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 that states the action and its consequence. It contains no filler or redundancies, making it easy to parse quickly.

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

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

The tool is simple: one required parameter with a clear schema, no nested objects, and an output schema is present. The description, combined with annotations and schema, gives an agent everything needed to decide when and how to call it. No return format explanation is needed because an output schema exists.

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 covers the single parameter (recommendation_id) with a clear description and 100% coverage. The tool description clarifies that the id is for a recommended company, which adds a bit of context, but it doesn't provide any info (like the id format or where to get it) beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Dismiss') and resource ('a recommended company') and fully captures the tool's unique scope by adding 'block it from future recommendations.' This clearly distinguishes it from the sibling tools recommendations.dismiss and inbox.dismiss, which only dismiss without the blocking side effect.

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 use case: when the agent wants both to dismiss the current recommendation and prevent future ones. It doesn't explicitly name alternatives or give 'use X instead' guidance, but the intent is unambiguous given the sibling list. A 4 is appropriate because the context is clear, though exclusions are not 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?

The description does not explain what dismissing means behaviorally, such as whether it is reversible, whether it hides the recommendation, or how it differs from blocking. The annotations already supply idempotentHint and destructiveHint, but the description adds little contextual behavior beyond the action itself.

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 no filler or redundant words. It immediately states the action and the object, which 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?

The tool is simple, has only two parameters, an output schema, and annotations covering safety semantics. However, the description omits important contextual details about how dismiss relates to block, restore, and feedback, which would help an agent make a more informed selection.

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

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

Schema description coverage is 100%, so the parameters are already well documented. The description adds no additional meaning about the recommendation_id or the reason field, so 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 uses a specific verb and resource: 'Dismiss a recommended company.' This clearly differentiates the tool from inbox.dismiss and other sibling tools by targeting recommendations specifically.

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 no guidance on when to use this tool over alternatives like recommendations.block, recommendations.restore, or inbox.dismiss. An agent would have to infer the right choice from naming conventions 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 description goes beyond the annotations by revealing that recording feedback has downstream effects: it sharpens future recommendations and the persona. Annotations already indicate this is a write operation, and the description adds meaningful context about persistence and learning.

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 focused sentence that states both the action and the strategic purpose. There is no filler, repetition, or unnecessary technical detail.

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

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

The tool is simple, has a well-documented schema, and includes an output schema. The description plus schema provide enough orientation for an agent to successfully invoke it. It could be slightly stronger with an explicit usage scenario or note about the feedback effect, but nothing critical is missing.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds general framing around fit and misfit, but it does not materially expand on what each parameter means or how they should be combined.

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 ('Record') with a clear resource ('why a recommendation was or was not a fit') and connects that to a system-level outcome. It does not explicitly distinguish itself from sibling tools like recommendations.dismiss or recommendations.block, but the concept of feedback is distinct enough that an agent can infer when this tool applies.

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

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

The description implies the tool should be used after a recommendation has been evaluated, since it records fit/non-fit reasons. However, it does not explicitly state when to use this tool over alternatives, nor does it mention exclusions or when not to use 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a useful behavioral/output cue by promising 'sources and persona fit' in the result, and nothing in it contradicts 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 entire tool is described in one front-loaded, information-rich sentence without filler or redundant restatements. Every phrase adds functional meaning.

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

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

For a single-parameter, read-only getter with a full schema and an output schema, this description is complete as-is. The description provides the core intent, and the schema/annotations cover the remaining invocation details.

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 covers 100% of the sole parameter and describes recommendation_id as 'Recommendation id', so the schema already does the heavy lifting. The description does not need to add parameter semantics, but it also contributes nothing else about the ID itself.

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 ('Get') and resource ('one recommended company') and further specifies the output contents ('with sources and persona fit'). The word 'one' clearly separates it from sibling tools like recommendations.list, so an agent can identify the likely operation 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?

The singular framing gives unambiguous context: use this when retrieving a single recommendation rather than a list. It does not explicitly name alternatives or give a when-not-to-use rule, which keeps it 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.