Refine Job Search

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 the 'upcoming' temporal scoping, which is useful context, but it provides no further behavioral details such as pagination, authentication needs, or response shape.

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 or redundant wording. It states the verb, resource, and scope efficiently, earning every word.

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 agenda tool, the description is complete. The read-only behavior is already covered by annotations, and the presence of an output schema means the description does not need to explain return values. The description sufficiently identifies what the tool returns and the scope of that return.

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

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

The tool has zero parameters, so the baseline is 4. The description's reference to 'upcoming' gives some semantic context about the implied time window, and there is no parameter schema for the description to compensate for.

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 a clear resource ('upcoming interviews and action items'). It is distinct from all sibling tools, none of which provide an account-level agenda view, so an agent can immediately identify what this 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?

The description clearly implies when to use this tool: when the agent needs upcoming interviews or action items for the account. It does not list exclusions or alternatives, but no sibling tool appears to overlap with this aggregate agenda function, so the context is reasonably clear.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds value by clarifying that the items are kept unchanged ('keep auto-applied items as-is') and that user confirmation is a prerequisite, which is not derivable from 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?

Two sentences with zero waste. The core purpose is front-loaded, and the confirmation requirement is stated succinctly.

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 an output schema available, so return values are already covered. The description covers the essential behavioral requirement (user confirmation) and the intent (finalize auto-applied items). Nothing an agent needs to call it correctly is missing.

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

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

Schema covers 100% of parameters with clear descriptions ('Inbox item ids to acknowledge' and 'Must be true after the user confirms'). The description adds no further parameter-level detail, so the baseline of 3 is appropriate when schema does the heavy lifting.

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

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

The description states a clear action ('keep auto-applied items as-is and finalize the automatic action') and the title 'Acknowledge inbox items' reinforces the verb-resource pair. It distinguishes itself from siblings like dismiss (which discards) and undo (which reverts) by implying these items are intentionally kept.

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 an explicit prerequisite: 'Confirm the specific items with the user first.' This tells the agent when to call the tool (after user confirmation) and implies it is the appropriate action for finalizing auto-applied items rather than declining, dismissing, or undoing them. It does not explicitly name alternatives, but the condition is clear.

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

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

Annotations already supply readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description adds value by giving examples of the actual effects (adding an application, recording a rejection) and reinforces the confirmation step. It doesn't contradict annotations, and it provides actionable behavioral context beyond the structured fields.

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

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

Two concise sentences front-load the core action and examples, followed by a direct usage instruction. There is no filler or redundancy, and every sentence earns its place.

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

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

The description covers the essential actions and the prerequisite confirmation step. Since there is an output schema, return value details are not required. It could have mentioned the irreversible nature or side effects more explicitly, but destructiveHint is already annotated, so the combination is adequate 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?

Schema description coverage is 100%, so both parameters are already documented. The description merely reiterates the confirmation requirement without adding new meaning beyond the schema. It does not clarify the format of item_id or elaborate on the confirmed constraint beyond what's present, so it meets the baseline for high schema coverage.

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

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

States a clear verb+resource: 'Apply an inbox item's suggested action' and provides concrete examples (adding to board, recording rejection). This distinguishes it from sibling actions like acknowledge, decline, or dismiss, which are more generic or different in intent.

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

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

The description explicitly instructs to confirm with the user first, which is a clear usage requirement. However, it does not differentiate when to use this tool versus alternatives such as inbox.acknowledge or inbox.decline, nor does it mention exclusions or conditions for other inbox operations. The guidance is present but not comprehensive.

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 this as destructive (destructiveHint=true) and non-read-only (readOnlyHint=false), and the description adds meaningful context beyond them: it queues replies and 'SENDS email from their address' depending on preference, a real external side effect the agent must communicate to the user. This external-sending behavior and the conditional dispatch are genuinely informative additions. No contradiction with annotations exists.

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

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

Three short sentences, each earning its place: tool purpose, the critical email-sending behavior, and the consent precondition. The purpose is front-loaded and there is no filler or repetition of schema content.

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

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

With an output schema and annotations that already cover return values and the destructive/write profile, the description covers the essential operational facts: queuing behavior, potential external email dispatch, and the explicit-approval gate. The only residual gap is ambiguity about whether declined replies are sent immediately or held for review, and the precise semantics of the preference enum 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 baseline is 3, but the description adds value by tying the preference parameter to its behavioral consequence — 'Depending on the user's preference this SENDS email from their address' — which the bare enum cannot convey. It also reinforces the confirmed parameter's role as an explicit approval gate. The exact meaning of each enum value (always/review/never) is still left to inference, so it stops short of a 5.

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

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

The description names a specific verb and resource — 'Queue decline replies to recruiter outreach' — which makes the tool's function unmistakable and distinguishes it from siblings like inbox.send_reply, inbox.draft_reply, and inbox.dismiss. The added disclosure that it may send email from the user's address further separates it from non-sending actions such as inbox.mark_read or 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?

The description provides an explicit invocation precondition: 'Only call after the user explicitly approved declining these specific conversations,' which properly gates a consent-sensitive operation. However, it names no sibling alternatives and gives no when-not-to-use guidance, so routing among inbox.dismiss and inbox.unsubscribe is left to the agent's inference.

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

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

Annotations already declare destructiveHint: true and readOnlyHint: false, so the description does not need to repeat those. It adds value by disclosing the Gmail read-marking side effect and (through the confirmed parameter) the requirement for user confirmation. No contradictions with 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, efficient sentence that front-loads the action and side effect. No wasted words; every part adds 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 high schema coverage and annotations covering the safety profile, the description provides sufficient context: purpose, when to use, and side effects. It does not explain the return value, but an output schema exists, so that is covered. The confirmation requirement is in the schema, and the description indirectly points to it.

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

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

The input schema already provides complete descriptions for both parameters (ids and confirmed), covering 100% of the semantics. The description reinforces the 'not acting on' context but doesn't add new meaning beyond what the schema already states. Baseline of 3 is appropriate given high schema coverage.

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

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

The description clearly states the action (dismiss), the resource (inbox items), and the context (items you are not acting on). It also distinguishes itself from similar tools like inbox.mark_read and inbox.acknowledge by explicitly noting the dismissal behavior and the Gmail read 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 phrase 'you are not acting on' provides implicit guidance on when to use the tool, implying it should be used when no further action is planned. It does not explicitly name alternatives or provide exclusion criteria, but the context is clear enough to guide an agent away from sibling tools like inbox.acknowledge or inbox.decline.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it returns related job and application, which is useful context beyond the annotations. However, it does not disclose potential error behavior or authentication requirements, so it adds limited incremental 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?

The description is a single sentence of nine words that is front-loaded with the action and resource. There is no redundancy or filler; 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 an output schema present and only one clearly documented parameter, the description is sufficient for an agent to call the tool correctly. It specifies the retrieval scope (related job and application) and the annotations cover safety. The only minor gap is that it does not mention behavior when the item is not found, but this is not critical for basic usage.

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 with the parameter description 'Inbox item id', and the description does not add any additional meaning or clarification about the parameter. Baseline 3 is appropriate since the schema already fully documents the parameter.

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 specifies the action ('Get'), the resource ('one inbox item'), and the scope ('with its related job and application'). This explicitly differentiates it from inbox.list (which retrieves multiple) and inbox.get_thread (which retrieves threads), giving an agent a precise understanding of what this 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?

The description does not explicitly state when to use this tool versus alternatives like inbox.list or inbox.get_thread. However, the singular 'one inbox item' implies it is for fetching a single item, which provides some implicit guidance. It does not name alternatives or exclusions, so the guidance is moderate.

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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that conversations are filtered to job search, but doesn't disclose pagination or ordering behavior. 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?

A single sentence that front-loads the action and scope. No filler or redundant phrasing.

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 and output schema cover parameters and return format, so the description is not required to repeat them. However, it lacks any usage guidance and doesn't highlight key filter options, making it only minimally 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 schema covers 100% of parameters with descriptions. The description only mentions the tab categories, which are already in the schema, so it adds no extra meaning.

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

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

The description uses a specific verb ('List') and resource ('email conversations') with a clear scope: 'matched to your job search' and enumerates categories (applications, interviews, recruiter outreach). It doesn't explicitly contrast with sibling tools, but the listing vs. fetching distinction is implicit.

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

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

No guidance on when to use this tool vs alternatives like inbox.get or inbox.refresh. The description only states what it does, not the context for selecting 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?

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 indicate this is a non-read-only, non-destructive, non-idempotent action. The description adds that it returns per-account sync status, which is useful context, but it does not disclose any side effects, prerequisites, or rate limits. Since annotations cover the safety profile, the added value is modest.

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 action and includes the return value. It is concise with no unnecessary information.

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

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

For a tool with no parameters and an output schema, the description provides the essential information: what it does and what it returns. It does not mention potential rate limits or authentication, but these are likely inherent to the action and not critical for choosing 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?

There are no parameters, so the description has nothing to add about parameter semantics. The empty schema fully covers the absence of parameters, meeting the baseline for a 0-parameter tool.

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

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

The description clearly states the action (check Gmail for new mail now) and the resource, and specifies the return (per-account sync status). It distinguishes itself from inbox.sync_status, which likely only reports status without triggering a check.

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

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

The word 'now' implies a manual forced refresh, but there is no explicit statement about when to use this tool versus alternatives like inbox.sync_status. No exclusions or alternatives are mentioned, so usage is implied rather than explicit.

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

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

Annotations already signal destructiveness (destructiveHint: true) and non-idempotency. The description adds real-world context ('emails a real person from the user's address') and reinforces the irreversible, consequential nature by linking it to explicit user approval. This goes beyond the structured annotations.

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

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

Two sentences, both high-value. The first states the purpose and the second states the critical precondition. No fluff, front-loaded with the action and the approval constraint.

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 send action, the description covers the approval requirement, the real-world impact, and the parameter linkage. Since an output schema exists, return values are already documented. Nothing essential is missing for an agent to call this safely and correctly.

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

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

Schema coverage is 100% and already includes descriptions for body and confirmed, including the requirement that confirmed must be true only after approval. The description reinforces this by saying the body must be exactly as approved, and the mention of draft_kind ('Set when the body came from inbox.draft_reply') adds useful cross-tool context not present in the schema.

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

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

The description states a specific verb (send) and resource (email reply via Gmail), and explicitly notes it emails a real person from the user's address, distinguishing it from drafting or applying suggestions. It clearly separates this from sibling tools like inbox.draft_reply.

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

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

Explicit when-to-use guidance: 'Only call after the user has seen the exact message body and explicitly approved sending it.' This is a strong guardrail that prevents premature or unauthorized sends. It also implies when not to call (without approval).

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 context that the status is per-account and includes progress and last sync time, but it does not explicitly state whether calling this can trigger a sync or refresh; annotations carry the main behavioral burden.

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 phrase that front-loads the core purpose ('Per-account Gmail synchronization status') and then adds the two most relevant data points. Every word adds value, with no redundancy or 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 zero-parameter, read-only tool with an output schema and annotations covering safety, the description is nearly complete. The only minor gap is the lack of explicit usage context relative to inbox.refresh and inbox.get, but the output schema likely resolves return-value questions.

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 100% schema description coverage, so there are no parameter semantics to clarify. The description's 'per-account' phrasing hints at account scoping through context rather than parameters, which is acceptable for a zero-parameter tool.

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

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

The description clearly identifies a specific resource: per-account Gmail synchronization status, and adds concrete return content ('current progress and last sync time'). This distinguishes it from siblings like inbox.get, inbox.list, and inbox.refresh, which deal with messages or triggering sync.

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 offers no guidance on when to use this tool versus alternatives. It does not mention that this is for checking sync progress rather than fetching emails or triggering a refresh, leaving the agent to infer usage from the name and sibling list.

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

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

Annotations already mark the tool as destructive, and the description adds specific, valuable behavioral detail: the undo operation can delete a board record created by the automatic action. It also communicates the safety requirement to confirm with the user, going beyond what the annotations alone 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 tight sentences deliver the purpose, the destructive consequence, and the required user-confirmation ritual. Information is front-loaded: the main action appears first, followed by the critical warning. 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?

Given the tool's moderate complexity, the annotations, and the presence of an output schema, the description covers the essential behavioral contract: what it undoes, what can be deleted, and the confirmation requirement. It does not elaborate on edge cases or results, but the existing schema and annotations cover enough for confident invocation.

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

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

The input schema fully documents both parameters, so the baseline is 3. The description adds extra meaning by tying the confirmation requirement to the user-confirm step and clarifying the real-world consequence of the item_id operation: deleting a board record. This reinforces the schema's parameter semantics rather than merely repeating them.

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

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

The description clearly states a specific verb ('Undo') and resource ('an auto-applied inbox action'), and then adds a concrete operational effect: it can delete a board record the action created. This distinguishes it from related inbox tools like inbox.dismiss or inbox.decline, and makes the tool's purpose immediately understandable.

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 context: this tool is for undoing auto-applied inbox actions, not manual ones, and it explicitly instructs to confirm with the user first. It does not name alternative tools or exclusion cases, but the usage context is clear enough for an agent to select it appropriately.

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

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

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

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

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

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

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

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

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

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

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

Schema description coverage is 100%, with item_id defined as 'Inbox item id' and confirmed as 'Must be true, and only after the user explicitly approved.' The description reinforces the confirmed parameter ('confirm with them before calling') but adds no additional meaning beyond the schema. Since the schema already documents both parameters adequately, a baseline score of 3 is appropriate.

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

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

The description explicitly states the tool's action: 'Unsubscribe the user from this sender's mailing list via one-click list-unsubscribe.' It identifies the resource (the user's subscription) and the condition (this sender). It also differentiates from siblings by saying 'Use it for unwanted bulk senders, not for a person you can simply decline,' which clearly separates it from tools like inbox.decline or inbox.dismiss.

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

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

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

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

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

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

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

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

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

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

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

For a tool with no parameters and a simple action (retrieving a link), the description is complete. It explains the purpose, the flow, and an important security constraint. The presence of an output schema likely covers the return value, so the description doesn't need to. Nothing essential is missing.

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

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

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

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

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

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

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

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

The description provides solid context: it tells the agent it's for connecting Gmail to Refine or approving missing permissions, and that Refine selects the permission. It also includes a critical security caveat: 'Share the link only with the owner of this Refine account.' However, it does not explicitly mention when not to use this tool or name alternative tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description doesn't need to restate safety. It adds the detail that the list includes 'grant status', which goes beyond annotations and informs the agent about the content.

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

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

Two sentences, front-loaded with purpose, and the alternative is given without extra words. Every sentence earns its place.

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

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

For a simple read-only list tool with no parameters, an output schema, and annotations covering safety, this description is complete. It explains what is listed and routes to the sibling for the complementary action.

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

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

The tool has zero parameters, so the description adds no parameter detail, and the baseline for zero parameters is 4. The description doesn't mislead or omit anything needed.

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

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

The description states a specific verb ('list'), resource ('connected Google accounts'), and the data ('grant status'). It explicitly distinguishes from the sibling integrations.connect_google, so an agent can tell them apart without opening schemas.

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

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

The description explicitly says 'To connect a new account, use integrations.connect_google', giving a clear when-not/alternative and implying this tool is for listing existing accounts. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is clear. The description adds minimal behavioral context beyond the generic 'add' action—it does not discuss side effects like duplicate handling or external integration, but it does not contradict annotations either.

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 zero waste. It is front-loaded with the core purpose. While it could use a bit more detail (e.g., what happens on duplicate), it remains appropriately short for a simple 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?

Given that an output schema is present (per context signals) and the 8 parameters are fully documented in the schema, the description provides sufficient context to use the tool correctly. It lacks clarification about prerequisites or distinct use cases, but for a straightforward 'add' operation, it is complete enough.

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

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

Schema description coverage is 100%, so all parameters are documented. The description adds no additional meaning about parameters, only implying that title and company are required. Baseline 3 is appropriate when the schema carries full 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?

The description states a specific verb ('Add'), resource ('job'), and context ('to your journey'), clearly distinguishing this from sibling tools like jobs.update or jobs.archive. It is immediately obvious what action this tool performs.

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 on when to use this tool versus alternatives like jobs.update or jobs.mark_applied. The description does not mention conditions, exclusions, or suggested alternatives, leaving the agent to infer usage from the name alone.

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

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

Annotations already supply idempotentHint=true and destructiveHint=false, covering safety profile. The description adds the key semantic that this operation is a 'hide' rather than a rejection or closure, which is valuable context beyond annotations. It does not go as far as describing side effects or reversibility, but given annotation coverage, the disclosure 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?

The description is a single, focused sentence that front-loads the primary action and scoping. Every phrase earns its place, with no redundant or filler content. It 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?

For a tool with one required parameter, an output schema, and safety annotations covering idempotency and non-destructiveness, the description is largely sufficient. It could optionally mention reversibility via jobs.unarchive, but this is not necessary for an agent to invoke the tool correctly. The core semantics are 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 input schema has 100% description coverage for job_id (described as 'Job id'), so the schema already documents the parameter. The description adds no additional meaning about the parameter's format, source, or usage, aligning with the baseline score of 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 clearly states the action ('Hide a job from the active board') and the resource, and it explicitly distinguishes from other outcomes ('without recording a rejection or closing the application'). This effectively separates it from rejection/closing operations and by context from delete/unarchive, making the purpose unambiguous.

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

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

The description implies the appropriate use case (hiding without rejecting), but it does not explicitly name alternative tools (e.g., jobs.delete, jobs.unarchive) or provide when-not-to-use guidance. The negative scoping ('without recording a rejection') hints at alternatives but leaves the agent to infer them from sibling names.

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

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

Beyond the destructiveHint and readOnlyHint annotations, the description adds key behavioral context: the deletion is permanent, affects both the job and its application, cannot be undone, and requires user confirmation. This materially helps an agent understand the consequences of invoking the tool.

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

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

Two sentences carry all essential information with no filler. The destructive consequence and confirmation requirement are front-loaded, and the alternative tool is mentioned succinctly in the second sentence.

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

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

For a simple destructive tool with two well-documented parameters, a rich annotation set, and an output schema, the description covers the critical operational context: irreversibility, cascade effect, confirmation requirement, and the relevant alternative. Nothing essential is missing.

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

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

Schema description coverage is 100%, with both job_id and confirmed already described in the input schema. The description reinforces the deletion behavior but adds no new parameter-level meaning beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description states a specific verb and resource: 'permanently delete a job and its application from the board.' It also differentiates itself from the sibling jobs.archive by explicitly naming the alternative usage, making the tool's scope unmistakable.

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

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

It gives a clear when-to-use instruction: confirm with the user first, and it explicitly tells the agent to use jobs.archive instead when the intent is to hide a job without recording a rejection or closure. This is direct guidance for tool selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds no additional behavioral context such as what details are included, error conditions, or whether archived jobs are returned. It merely restates the read-only nature implicitly, providing no value beyond 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, concise sentence with no filler or redundancy. It front-loads the action and resource, making it immediately actionable. It is appropriately sized for a simple single-resource retrieval 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?

Given the simple one-parameter schema, full annotations, and an output schema that defines the return value, the description is adequate. It does not mention edge cases like non-existent jobs, but those are not critical for correct invocation. The tool is simple enough that the description, annotations, and schema together provide sufficient context.

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

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

Schema coverage is 100% since job_id has a description ('Job id'). The description does not add any meaning beyond what the schema provides. The baseline of 3 applies because the schema handles the parameter documentation entirely.

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 ('Get') and resource ('details of a specific job'), making it clear this retrieves a single job by ID. The word 'specific' implicitly distinguishes it from jobs.list which retrieves multiple jobs, so an agent can tell them apart without extra clarification.

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 like jobs.list or jobs.update. There is no mention of prerequisites, conditions, or exclusions. The agent must infer typical usage from the name and schema, which is insufficient for proactive 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 indicate readOnlyHint false, destructiveHint false, and idempotentHint false, which align with the 'Log' action implying a non-destructive write. The description adds no extra behavioral context (e.g., side effects, auth needs, or validation). Consistent with annotations but contributes minimal additional 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, clear sentence with no unnecessary words. It is appropriately sized for a simple CRUD-style operation and front-loads the core intent.

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 add tool with a full schema and an output schema present, the description is adequate but minimal. It does not mention that a valid job_id is required (though schema marks it required), nor does it clarify the relationship with 'jobs.interviews.update' for modifications. Given the schema richness, this is acceptable but leaves room for more context.

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

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

Schema description coverage is 100% – all five parameters have descriptive text in the schema (e.g., 'Interview name', 'Notes or debrief', 'ISO 8601 date/time with timezone'). The description provides no parameter-specific elaboration, so baseline 3 is appropriate since the schema already documents each parameter.

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 ('Log') and the resource ('an interview for a job'), and the tool name 'add' distinguishes it from its siblings 'delete' and 'update'. However, it does not explicitly reference those siblings, leaving the differentiation to be inferred from the naming convention.

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 on when to use this tool versus alternatives. There is no mention of 'use when creating a new interview' or 'use update to modify an existing one'. The sibling tools exist but are not referenced, so an agent must 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?

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds the critical detail 'cannot be undone' (reinforcing permanence) and mandates user confirmation, both of which go beyond the structured annotations.

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

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

The description is a single sentence with no wasted words. It front-loads the action and permanence, then adds the confirmation requirement—every clause contributes.

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

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

For a simple 3-parameter delete operation with annotations covering destructive/idempotent behavior and an output schema present, the description provides all necessary context: action, permanence, and confirmation requirement. It could optionally note alternatives, but that is not essential for correct invocation.

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

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

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

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

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

The description uses a specific verb ('Permanently delete') and identifies the exact resource ('an interview from a job'). It clearly distinguishes from sibling tools like jobs.interviews.add and jobs.interviews.update by emphasizing irreversibility.

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

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

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

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

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

Annotations already declare destructiveHint=false, idempotentHint=true, and readOnlyHint=false, covering the safety profile. The description adds no behavioral context beyond that, such as whether updates are partial, what happens on missing records, or any side effects. It fails to add value over the structured annotations.

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

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

The description is a single, terse sentence that front-loads the core action without any wasted words. It is efficient and concise, though it sacrifices depth for brevity. This is acceptable for a tool whose schema conveys the 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?

The tool has many optional parameters, but the schema fully documents them. The description implies that the interview must already exist ('existing') but does not mention any preconditions or constraints, such as whether fields can be updated independently. Given that an output schema exists and the input schema is thorough, the description is minimally sufficient but not richly contextual.

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 provides detailed descriptions for all 14 parameters, achieving 100% coverage. The description contributes no additional meaning to the parameters, relying entirely on the schema. With such high schema coverage, 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 clear action and resource ('Update an existing interview') with no ambiguity. The word 'existing' hints at modification rather than creation, which loosely differentiates it from jobs.interviews.add. However, it does not explicitly name sibling tools or describe what fields are updatable, relying on 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?

No explicit guidance is provided on when to use this tool versus jobs.interviews.add or jobs.interviews.delete. The description only states the operation, leaving the agent to infer that it is for modifying existing records. It lacks any conditions, alternatives, or exclusions.

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

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

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description needs little here. It adds only the scoping phrase 'in your journey'; no side effects, auth, or pagination behavior are mentioned, but none are critical for a read-only listing.

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

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

A single sentence, no filler, and the core action is front-loaded. Every word contributes.

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

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

With output schema present, rich annotations, and fully documented optional parameters, the tool is callable. However, 'journey' is left undefined and there is no hint distinguishing this list from job-related siblings, so the description is adequate but not 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 description coverage is 100%, with page and limit already documented, so the description bears no burden here. It adds no additional parameter meaning, which is acceptable at baseline.

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

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

States a specific verb and resource ('List jobs') and adds a scope qualifier ('in your journey'), which distinguishes it from single-record tools like jobs.get. The word 'journey' is somewhat domain-specific but not misleading.

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

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

No guidance on when to choose this instead of siblings such as jobs.get, jobs.refresh, or signals.list_applied_jobs. 'List' implies a collection operation, but the description never states exclusions or alternatives.

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

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

Annotations already declare idempotentHint=true and destructiveHint=true, and the description adds no further behavioral context. It does not explain what 'mark as applied' implies (e.g., job status change, career history update) or any side effects beyond the annotation hints. The description contributes nothing beyond the 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?

The description is a single, front-loaded sentence with a clear verb and object. It contains no fluff or redundancy, making it appropriately concise for a simple tool with a single parameter. 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?

Given the tool's simplicity (one parameter, output schema present) and the annotations covering safety (idempotent, destructive), the description is minimally sufficient. However, it lacks any note about when to invoke this action, prerelease conditions (e.g., job must exist), or consequences beyond the annotation hints. It is complete enough for a straightforward mutation but misses a chance to add valuable 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 covers 100% of the parameters, providing a description for job_id ('Job id'). The tool description does not add any additional meaning to the parameter; it relies entirely on the schema, which is complete for this single parameter. Baseline 3 is appropriate because the schema already documents the parameter fully.

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 'Mark a job as applied' clearly identifies the action (mark applied) and the resource (job). It is unambiguous, but it does not explicitly differentiate from siblings like jobs.update or signals.list_applied_jobs, relying on the verb 'mark applied' to convey uniqueness.

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. It does not mention that this tool should be used after submitting an application, nor does it contrast with jobs.update or other job-state-changing tools. The agent is left to infer usage from the name alone.

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

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

The description discloses that accepting the offer is a major state change that closes out the search, going beyond the annotations that only mark destructiveHint=true. It also adds a specific non-behavior (does not email the employer), which is useful context not present in annotations. No contradiction with annotations; it actually enriches them.

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

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

The description is two sentences, front-loaded with the core action, followed by critical warnings and a limitation. There is no fluff or redundancy. Every sentence serves a purpose: defining the action, highlighting the state change/confirmation requirement, and noting what it does not do.

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

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

The tool has only two parameters, both fully covered by the schema, and an output schema is present, so return values are not needed in the description. The description covers the key behavioral aspects: the destructive nature, the need for confirmation, and the absence of employer notification. It is complete enough for an agent to invoke correctly, though it could theoretically mention the impact on related job status, but this is adequately implied by 'closes out the search.'

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

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

Schema coverage is 100%: both job_id and confirmed are described in the schema. The description does not add extra parameter-level semantics beyond what the schema already provides, so the baseline score of 3 applies. The description's mention of user confirmation aligns with the confirmed parameter but does not add new information.

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: 'Accept the offer for a job.' It further defines the scope by noting it 'closes out the search for this role,' which differentiates it from other offer-related siblings like decline or create. The verb and resource are specific, and the intent is unambiguous.

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

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

The description gives an explicit precondition: 'confirm with the user before calling.' This is a crucial usage guideline for a destructive action. It also provides a negative constraint by stating it does not email the employer, clarifying what the tool does not do. While it doesn't explicitly name alternatives (e.g., decline), the purpose is clear enough to select this tool for acceptance.

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 it as a non-destructive write (readOnlyHint=false, destructiveHint=false). The description adds little behavior: it doesn't state whether events append to an ongoing negotiation, whether multiple events per offer are allowed, or that it does not alter the offer's terms. No contradiction with annotations, but limited added 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?

A single front-loaded sentence that conveys the core action plus useful parenthetical examples. No padding or redundancy. It could earn a 5 if it also surfaced the sibling relationship, but it's not overwritten.

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

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

An output schema, complete parameter schema, and annotations cover return values and safety profile. The main gap is the description's silence on how it relates to sibling offer tools and whether negotiation events are append-only. Adequate but thin for an agent choosing among several jobs.offer.* tools.

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

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

Schema description coverage is 100% with all 7 parameters documented (job_id, event_type enum, event_date format, notes, bonus_cents, equity_text, salary_cents). The description adds no parameter detail, which is appropriate given the schema already carries full semantics. Baseline 3 applies.

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

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

The description names a specific verb and resource ('Log a negotiation event on an offer') and gives concrete examples of what qualifies (counter-offer, update). It is clear enough to distinguish the action from offer create/update/delete at a high level, though it doesn't explicitly contrast with siblings like jobs.offer.delete_negotiation or jobs.offer.update.

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

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

No guidance on when to use this tool versus alternatives. It never mentions when to prefer jobs.offer.update (for changing terms) over logging an event, or how it relates to create/delete_negotiation. The examples hint at negotiation-logging scenarios, but there are 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?

The description adds no behavioral context beyond the annotations. Annotations already signal it is a non-read-only, non-destructive, non-idempotent operation, but the description does not add details such as side effects, permissions, or calls tied to the required job_id. It merely restates the purpose.

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 wasted words. It is front-loaded with the action and resource, though it could have used the space to mention that it creates a new offer or reference an alternative without becoming verbose.

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, annotations, and output schema cover most operational details, so the minimal description is not crippling. However, with 17 parameters and a clear sibling group for offer management, the description omits needed context about creating vs. updating an offer and what 'record' implies for an existing job.

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

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

Schema description coverage is 100%, and each parameter has its own description in the schema, so the baseline is 3. The phrase 'with compensation details' loosely captures the parameter set but adds no meaning beyond what the schema already provides.

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

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

The description states a specific verb ('Record'), a resource ('a job offer'), and a key data area ('with compensation details'). It is clear enough to tell this apart from siblings like jobs.offer.accept or jobs.offer.decline, though it does not explicitly contrast with jobs.offer.update.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention that this creates a new offer, nor does it reference jobs.offer.update for modifying existing offers, leaving usage context entirely to inference from the tool name and sibling list.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds valuable context beyond annotations: that it is a major state change, requires user confirmation (not captured in annotations), and explicitly states it does not email the employer. This gives the agent a clearer picture of side effects without contradicting 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, efficient sentence that front-loads the primary purpose, then adds the confirmation requirement and a key side effect. Every phrase contributes useful information with zero 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 mutation tool with an output schema and two parameters, the description covers the essential aspects: purpose, confirmation requirement, and a notable side effect. It does not mention the exact output, but the output schema exists. The idempotent behavior is already in annotations, so nothing critical is missing 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 explains both parameters: job_id and confirmed. The description adds no additional meaning about parameters. Baseline 3 is appropriate since the schema handles 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?

The description clearly states this tool declines a job offer, a distinct action from accepting or deleting an offer. It uses a specific verb (Decline) and resource (offer for a job), and the addition of 'major state change' reinforces its purpose as a consequential action.

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

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

The description includes a critical prerequisite: 'confirm with the user first'. However, it does not explicitly state when to use this tool versus alternatives like accepting, deleting, or negotiating the offer. The sibling names imply the context, but explicit guidance is missing.

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

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

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

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

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

The description is two short, purposeful sentences. The first sentence states the action and scope; the second provides usage conditions and consequences. There is no redundancy or fluff; every clause earns its place.

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

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

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

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

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

The schema already describes both job_id ('Job id') and confirmed ('Must be true after the user confirms permanent deletion') with 100% coverage. The description does not add new details about the parameters beyond reinforcing that confirmation is required, which is already in the schema. Hence the baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'delete' and the resource 'offer recorded for a job', and explicitly notes 'the job stays' to distinguish from jobs.delete. This unambiguously identifies what the tool does and differentiates it from sibling tools like jobs.delete or jobs.offer.update.

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

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

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

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

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

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

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

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

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

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

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

Given the tool's simplicity, the description is adequate. The annotations cover destructive and idempotent hints, and the schema documents all parameters including the confirmation requirement. However, it lacks any warning about the irreversible nature or any expected outcome, which would be helpful for a destructive operation. Still, the essential information is present.

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

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

Schema description coverage is 100%, and each parameter has a description (job_id: 'Job id', event_id: 'Negotiation event id', confirmed: 'Must be true after the user confirms deletion'). The tool description adds no additional parameter meaning beyond what the schema already provides, so it meets the baseline without enhancement.

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

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

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

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

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

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

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

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

The description simply states 'update' without revealing any additional behavior. Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the description adds no new context about side effects, validation, or error handling. It neither contradicts nor enriches 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, well-structured sentence with zero superfluous words. It front-loads the action ('Update') and the object ('offer'), making it immediately clear what the tool does. It earns high marks for efficiency and clarity.

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

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

Given the complexity (17 parameters) and presence of an output schema, the description is minimally acceptable but lacks context about update semantics (e.g., whether unspecified fields are left unchanged) and when to choose this over related offer tools. The schema covers parameter details, but the description does not address broader usage context beyond the basic action.

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

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

With 100% schema description coverage, all 17 parameters are already documented in the input schema. The description does not add any extra meaning beyond the schema, such as explaining that only some fields are updatable or how partial updates are handled. Baseline 3 applies because the schema carries the full explanatory burden.

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 'Update the offer recorded for a job' clearly specifies the verb (update) and resource (offer recorded for a job), which directly distinguishes it from sibling tools like jobs.offer.accept, jobs.offer.decline, and jobs.offer.create. It is concise and unambiguous, effectively communicating the tool's primary function.

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. It does not mention any conditions, prerequisites, or scenarios where jobs.offer.create or jobs.offer.add_negotiation would be more appropriate. An agent is left to infer usage solely 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 indicate this is a mutation (readOnlyHint=false) and not idempotent, but the description adds key behavioral context: the operation is asynchronous ('may remain pending') and requires polling via jobs.get. This goes beyond what annotations provide, clarifying the eventual consistency and the way to obtain results. No contradiction with annotations.

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

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

The description is two concise sentences that lead with the core action and immediately provide the critical asynchronous behavior and follow-up step. There is no unnecessary detail, and the structure is front-loaded for quick comprehension.

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 queueing tool with a well-covered schema and existing output schema, the description sufficiently conveys the operation's async nature and how to verify results. It does not cover potential error states or edge cases, but these are not essential for correct invocation. Given the tool's simplicity, this is complete enough.

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

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

The schema already describes job_id as 'Job id' with 100% coverage, so the description adds little about the parameter. It indirectly associates job_id with the 'job posting' being re-scraped, but this is also evident from the tool name. The baseline of 3 is appropriate since the schema handles 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?

The description clearly states the tool's purpose: 'Queue a job posting to be re-scraped.' This specifies the action (queue a re-scrape) and the resource (job posting), distinguishing it from siblings like jobs.delete, jobs.archive, and inbox.refresh. The resource and intent are unambiguous.

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

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

The description implies the tool is for triggering a re-scrape but does not explicitly state when to use it versus alternatives, nor any exclusions. It does give a follow-up instruction—'use jobs.get later to inspect the refreshed state'—but that is post-usage guidance rather than selection criteria. No alternatives or when-not-to-use conditions are mentioned.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, covering the mutation safety profile. The description adds the destination 'active board' but no extra behavioral context like idempotency effects or error conditions. No contradiction with 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, front-loaded sentence that states the action and destination with zero 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?

The tool is simple: one required parameter, output schema exists, annotations cover safety. The description is sufficient for an agent to call it correctly. It could mention prerequisites like 'job must already be archived', but that's a minor omission.

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 the single parameter job_id with a description 'Job id', providing 100% coverage. The tool description adds no additional parameter semantics, so the baseline of 3 applies.

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

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

The description states a clear verb (restore), a specific resource (an archived job), and a goal (to the active board). This distinguishes it from siblings like jobs.archive and jobs.delete, making its purpose unambiguous.

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

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

While there's no explicit when/when-not guidance, the description clearly implies this is the inverse of jobs.archive, and an agent can infer usage from the name and wording. It provides context but doesn't exclude alternatives or mention edge cases.

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 nothing beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false). It doesn't disclose update semantics like merge vs replace, validation behavior, or what happens when fields are omitted, so it fails to add behavioral context.

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

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

The description is a single short sentence, which is concise, but it adds little value beyond the title. It is not rambling, but it doesn't earn its place by providing necessary context.

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

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

For a tool with 10 parameters and an output schema, this description is severely incomplete. It doesn't explain update behavior, payload expectations, or how it differs from other update tools, leaving an agent to infer critical 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?

Schema description coverage is 100%, so each of the 10 parameters is already documented. The description adds no parameter-specific information, so the baseline 3 applies.

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

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

The description states the action (update) and object (job), which distinguishes it from add, delete, and get. However, 'in your journey' is vague and the description doesn't specify the scope or differentiate from jobs.interviews.update or jobs.offer.update, so it's clear but not fully specific.

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 on when to use this tool vs alternatives, whether it's a partial or full update, or any prerequisites like job existence. It does not reference sibling tools or specify exclusions.

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

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

Annotations already declare 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the scope 'you are tracking' but does not disclose any additional behavior such as pagination defaults or whether paused signals are excluded. No contradiction with annotations exists.

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

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

One short, front-loaded sentence with no filler. 'List companies you are tracking' efficiently conveys the resource and filter without wasting tokens.

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

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

For a read-only list with optional pagination, the description plus parameter schema and annotations are sufficient. The only minor gap is the lack of an explicit pointer to sibling list tools, but the scope is clear. Since an output schema exists, return values need not be described.

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 (page, limit) have schema descriptions that fully define them; the description adds no extra parameter meaning. With schema description coverage at 100%, 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 uses the specific verb 'list' with a clear resource ('companies') and a scope qualifier ('you are tracking'), which makes it distinct from sibling tools like signals.track/untrack (mutations) and signals.list_applied_jobs (different resource). No ambiguity remains about the operation's intent.

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

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

The description implies the use case (viewing tracked companies) but does not explicitly contrast with alternatives such as signals.recommendations.list or signals.list_applied_jobs. No when-not-to-use guidance is provided, leaving selection to inference from the name and scope.

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, idempotentHint, destructiveHint, covering the safety profile. The description adds little beyond the annotations: it mentions 'in your journey' and 'tracked company', which aligns with the required signal_id, but no pagination details, ordering, or filtering behavior beyond what schema already states. No contradiction with 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, efficient sentence with no filler. It front-loads the core purpose with zero waste, which is optimal for such a simple list 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?

For a list tool with pagination and an output schema, the description is adequate but not complete. It doesn't explain what 'your journey' means (e.g., application progress) or when to prefer this over other list tools. However, the output schema and annotations cover many operational details, so it's sufficient but not exemplary.

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

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

Schema coverage is 100% with descriptions for all three parameters, so the schema carries the meaning. The description adds context that 'signal_id' refers to a tracked company, but that is also in the schema description. No significant extra semantics beyond a 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 clearly states the action (list) and resource (jobs in your journey that came from a tracked company), which distinguishes it from siblings like signals.list (lists signals) and jobs.list (all jobs). It is specific but does not explicitly contrast with alternatives, so slightly below top.

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

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

No guidance on when to use this tool vs. alternatives such as signals.list, signals.openings.list, or jobs.list. The description is purely declarative without any conditional or comparative hints.

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 readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety bar is low. The description is consistent with the annotations. It adds no behavioral context beyond what annotations provide, such as pagination behavior or filter semantics, but the schema covers most of that via descriptions.

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

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

A single efficient sentence with no waste, and the clarifying parenthetical is front-loaded. The trade-off is that brevity comes at the cost of usage guidance, but as pure conciseness it scores well.

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?

Completeness is adequate: output schema present, all 8 params documented, annotations covering safety. The main gap is usage discrimination guidance across the many signals.* siblings, which would materially help an agent select the right tool. Pagination is covered by meta.next_page in the schema, so nothing critical is missing there.

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

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

Schema description coverage is 100%, with all 8 parameters individually documented (tab enum, page cursor, limit, matches, location, department, tracker_id). The description adds no parameter-level detail, but the high schema coverage warrants the baseline score of 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?

States the verb 'List' and resource 'signal notifications', with the clarifying parenthetical 'new openings at tracked companies' that distinguishes it from signals.list (trackers) and signals.recommendations.list. However, it doesn't name any sibling tool explicitly, so differentiation relies on the parenthetical 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?

No guidance on when to use this tool vs alternatives. With a crowded sibling set (signals.list, signals.recommendations.list, inbox.list, jobs.list), there is no when-to-use/when-not-to-use statement. The parenthetical hints at scope but provides no selection criteria for an agent.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the critical behavioral constraint that user confirmation is required before the bulk action executes, which is not explicit in the annotations. It does not repeat what annotations already state, adding value without redundancy.

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

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

A single, efficient sentence that leads with the core function and then states the condition. No filler or wasted words, and the most important information 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 simple one-parameter tool with an output schema and comprehensive annotations, the description covers every essential aspect: what it does, the condition for use, and the scope. The bulk vs. singular distinction is implied by the wording, and the confirmation requirement is explicit. Nothing an agent needs to invoke it correctly is missing.

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

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

With 100% schema description coverage, the single parameter 'confirmed' is already fully documented in the schema ('Must be true after the user confirms marking all openings read'). The tool description's phrase 'after the user confirms the bulk action' essentially repeats this same semantics, adding no new meaning 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 clearly states the action (mark as read), the exact scope (every unread opening notification), and the prerequisite (user confirmation). It distinguishes itself from sibling signals.openings.mark_read by emphasizing the bulk nature ('every unread', 'bulk action'), leaving no ambiguity about what it 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?

The description specifies the condition for use: only after user confirmation. It does not explicitly name alternatives like signals.openings.mark_read for single notifications, but the wording 'every unread' and 'bulk action' strongly conveys that this is for bulk operations. It lacks an explicit exclusion clause, so it stops short of a perfect 5.

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

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

Annotations already communicate idempotentHint=true and destructiveHint=false, so the description does not need to restate safety behavior. It adds the scoping detail that only notifications from signals.openings.list are accepted, matching the annotations without 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?

A single, front-loaded sentence contains the verb, resource, source, and scope with no filler. 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 one-parameter, idempotent, non-destructive mutation with full schema coverage and an output schema, the description plus annotations leave no material gap. An agent can determine the input source and effect.

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

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

Schema coverage is 100% and notification_id is already described as the id from signals.openings.list. The description repeats this relationship but adds no new parameter-level detail, so the baseline 3 is appropriate.

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

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

Description states a specific action ('Mark ... as read'), a precise resource ('one opening notification'), and its origin ('returned by signals.openings.list'). This distinguishes it from the sibling signals.openings.mark_all_read without needing to inspect 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 proper workflow: call signals.openings.list first, then mark a returned notification. It does not explicitly contrast with mark_all_read or state when not to use this tool, but the singular 'one' plus the referenced list tool provides a clear usage 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 establish the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds destination context — the save targets the job journey. It does not disclose edge behaviors such as what happens on duplicate saves or whether saving removes the opening from the open list, so the added behavioral context is modest. No contradiction with annotations.

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

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

A single 14-word sentence front-loads the verb and object, then packs provenance and destination with zero 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 one-parameter tool with a fully documented schema and an output schema, the working contract is nearly complete: action, source, and destination are all stated. Remaining gaps are workflow routing (save vs. mark_read vs. jobs.add) and defining 'job journey,' which are minor for a tool this simple.

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

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

Schema description coverage is 100%, and the schema already defines opening_id as 'Matched opening id from signals.openings.list.' The description merely reinforces that provenance without adding format, syntax, or default details. Under high schema coverage, baseline 3 applies.

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

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

The description names a specific verb ('Save'), a clear resource ('a matched opening'), its provenance ('returned by signals.openings.list'), and a destination ('your job journey'). This unambiguously distinguishes it from siblings like signals.openings.list, signals.openings.mark_read, and jobs.add.

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 implicitly specifies the precondition: the input must come from signals.openings.list, so the agent knows to call that tool first and pass only ids it returns. However, it does not explicitly name alternatives such as signals.openings.mark_read or jobs.add, nor state when not to use this tool. Clear context, but no explicit exclusions.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, covering the safety profile. The description aligns with these (pause implies a non-destructive, repeatable action) but adds no extra behavioral detail about side effects, reversibility, or what exactly gets paused. It does not contradict annotations.

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

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

A single clear sentence with no redundant words. It is appropriately sized for a simple tool and gets straight to the point.

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

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

For a simple state-change tool with one parameter, the description is acceptable but lacks context about the pause lifecycle—what happens to the company's signals while paused, whether historical data is affected, and that signals.resume reverses the action. Given that an output schema exists and annotations cover safety, the description is minimally sufficient but not thorough.

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 signal_id has full schema coverage with the description 'Signal (tracked company) id', so the schema already documents it. The tool description adds no additional meaning or usage nuance beyond the schema.

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

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

The description states a specific verb (Pause) and resource (tracking for a company), making it clear what the tool does. It distinguishes from sibling signals.resume and signals.untrack by the verb, though it could briefly clarify that pausing is temporary and reversible.

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

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

No guidance on when to use this tool versus alternatives like signals.resume or signals.untrack. An agent is left to infer that pause is for temporary halts, but the description does not explicitly mention when-not-to-use or suggest related tools.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, and the description's 'block it from future recommendations' is consistent with these. The description adds no extra behavioral context such as reversibility or impact on the current recommendation list, so it does not exceed what the annotations convey.

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

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

The description is a single, concise sentence that conveys both the immediate action and the long-term effect without any redundant words. It is well-structured for a simple one-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 simple tool with one parameter, an output schema, and safety annotations, the description is nearly complete. The only missing context is explicit information about reversibility or how this relates to restore/dismiss, but the core calling behavior is fully 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 already covers 100% of the single parameter recommendation_id with a clear description ('Recommendation id'), so the description adds no new semantic meaning. This matches the baseline for high schema coverage.

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

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

The description clearly states the action ('Dismiss a recommended company') and the outcome ('block it from future recommendations'), making the tool's purpose specific and understandable. However, it does not explicitly distinguish itself from sibling tools like signals.recommendations.dismiss, relying on the word 'block' to imply the difference.

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 usage when a user wants to permanently remove a company from future recommendations, but it does not provide explicit when-to-use or when-not-to-use guidance. No alternatives are mentioned, so the agent must infer the boundary between this and similar dismiss/restore tools.

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

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

Annotations already indicate idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds no further behavioral context beyond 'dismiss', but it 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?

The description is a single, front-loaded sentence with no filler, no repetition of the schema, and no unnecessary detail. It is as concise as a description can be while still stating the core action.

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

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

For a simple tool with full schema parameter documentation, output schema, and annotations covering safety and idempotency, the one-sentence description is largely sufficient. A pointer distinguishing dismiss from block or restore would strengthen completeness, but that gap is already reflected in the usage guidance score.

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

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

Schema description coverage is 100%, with both recommendation_id and reason explained in the schema; reason even notes that it sharpens future recommendations. The tool description adds no parameter-level meaning beyond what the schema already provides, 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 names a specific verb ('dismiss') and resource ('a recommended company'), clearly indicating what the tool does. It doesn't explicitly distinguish this from sibling tools like signals.recommendations.block or signals.recommendations.restore, so it isn't a full 5.

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

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

The description gives no guidance on when to use dismiss versus sibling recommendation actions such as block, restore, feedback, or watch. An agent receives no exclusions or alternative conditions, leaving the selection decision to inference 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?

Annotations already indicate it is a non-read-only, non-idempotent operation, but not destructive. The description adds a side-effect statement: 'this sharpens future recommendations and the persona', which discloses that it affects future behavior. However, it omits any mention of auth requirements, rate limits, or details about what happens to the recommendation itself (e.g., does it also dismiss it?), which with the low annotation bar leaves moderate 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, well-structured sentence with no filler. It front-loads the purpose ('Record why') and adds a consequence clause that explains the value. 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 mutation with high schema coverage and an output schema, the description covers the core action. However, it lacks guidance on how this relates to sibling tools (e.g., whether feedback should precede or replace dismiss), and it doesn't clarify the effect on the recommendation's state. This leaves an agent potentially unsure about the intended workflow.

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

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

Schema description coverage is 100%, so all parameters have descriptions. The description adds minimal specific parameter meaning—only that feedback_types captures 'why a recommendation was or was not a fit', which is already implied by the enum. The baseline of 3 is appropriate since the schema carries the primary semantic load.

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 'Record' and the resource 'why a recommendation was or was not a fit', indicating a mutation that logs reasoning. It distinguishes from sibling tools like dismiss or block by focusing on capturing reason rather than performing an action on the recommendation, though it doesn't explicitly name the difference.

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 on when to use this tool versus alternatives such as signals.recommendations.dismiss, block, or watch. The description implies it is for recording reasoning but does not state conditions, prerequisites, or when not to use it, leaving the agent to infer.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds that the response includes 'sources and persona fit', which is useful but likely also reflected in the output schema. No contradiction with annotations; the added value beyond structured data is minimal.

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 zero unnecessary words. It states exactly what is returned and the key differentiator ('one'). This is exemplary conciseness.

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

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

Given the tool's simplicity (one parameter, output schema present, annotations covering safety), the description is complete. It names the resource, the scope (one), and the contents (sources, persona fit). No critical information is missing for an agent to decide and 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% for the single parameter, so the schema already conveys everything about recommendation_id. The tool description does not add extra meaning about parameter formats, constraints, or usage beyond implying it identifies a specific recommendation. 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 verb 'Get' and the specific resource 'one recommended company' with its key attributes (sources and persona fit). It distinguishes this from listing many recommendations (signals.recommendations.list) and from mutating actions like dismiss or block. The word 'one' makes the intent unambiguous.

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

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

No explicit when-to-use guidance is given. However, the requirement of a recommendation_id and the contrast with list imply it is for fetching a single recommendation's details. The description does not name alternatives or exclusion conditions, leaving that to inference from 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds useful context about the per-company scope and the signal_id prerequisite, but it does not disclose any additional behavioral traits such as pagination behavior or output shape, though an output schema exists.

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

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

The description is only two sentences with no filler. The first sentence front-loads the verb, resource, and scope; the second immediately tells the agent how to obtain the required parameter. Every sentence earns its place.

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

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

Given the rich input schema, output schema, and annotations, the description is complete enough for correct invocation. It states the action, the scope, and the source of the required signal_id, while the schema covers pagination and limits and annotations cover the safety profile.

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%: signal_id is described as 'Tracked-company id from signals.list', page as a pagination cursor, and limit as a maximum record count. The description only repeats the signal_id provenance and does not add meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb ('List'), a specific resource ('companies recommended from one company you track'), and tells the agent where to obtain the required signal_id ('Get signal_id from signals.list'). This clearly distinguishes it from signals.list and signals.recommendations.get, whose sibling names suggest different 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?

The description gives clear context for when to use this tool: to list companies recommended from one tracked company, and it points to signals.list as the source of signal_id. It does not explicitly name alternatives or state when not to use it, but the context is sufficient and not misleading.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, covering safety. The description adds the specific states it reverses, which is useful context, but it does not disclose any side effects or requirements beyond what the annotations imply. With annotations carrying the safety load, this is a reasonable score.

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 conveys the essential purpose immediately, exemplifying conciseness.

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 and an output schema, the description is barely adequate. It does not mention what the restore operation returns or any error conditions, but these are likely covered by the output schema. The description covers the key state context, making it complete enough without being verbose.

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

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

Schema coverage is 100%, and the parameter is already described as 'Recommendation id'. The description does not add any extra semantic nuance beyond what the schema provides, so the baseline of 3 applies.

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

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

The description clearly states a specific verb ('Restore') and resource ('recommendation'), and specifies the states it applies to ('dismissed or blocked'). This distinguishes it from sibling tools like dismiss and block, making its purpose unambiguous.

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

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

The description implies when to use the tool: when a recommendation was previously dismissed or blocked and needs to be re-enabled. However, it does not explicitly mention alternatives or when not to use it, so it falls short of the highest score but provides clear contextual 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 establish readOnlyHint=false, idempotentHint=false, and destructiveHint=false — marking it as a mutating, non-idempotent, non-destructive operation. The description adds the state-transition detail that a recommendation becomes a signal (openWorldHint=true, so effects likely extend beyond the return value). It does not disclose reversibility or side effects beyond the conversion, but it does add value over 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, front-loaded sentence that names the action, the target, and the resulting state with zero wasted words. It is not padded, though it is terse enough to omit usage guidance that would elevate it further.

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

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

With one fully-documented parameter, an output schema, and annotation coverage, the tool is nearly complete. The main gap is the absence of usage/selection guidance relative to the signal-tracking sibling cluster, which prevents a higher score.

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

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

Schema description coverage is 100% and the single parameter recommendation_id is straightforwardly documented ('Recommendation id'). The description adds no additional meaning beyond the schema, so the baseline of 3 applies — adequate but no extra value.

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 ('Start tracking a recommended company') and adds the conversion clause ('converts it into a signal') that clarifies what the action accomplishes beyond the bare verb 'watch'. It is clearly distinct from recommendation-related siblings like block/dismiss/restore, though it does not explicitly differentiate itself from the similarly-named signals.track 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?

No guidance is given on when to use this tool versus alternatives. With siblings signals.track, signals.untrack, signals.recommendations.block, and signals.recommendations.dismiss all nearby, the description provides no selection criteria or exclusions, leaving the agent to infer intent from the name alone.

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