doom

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

With no annotations, the description carries the full behavioral disclosure. It clearly states the tool is async, returns a job_id, defaults to 'deep' mode, and allows an optional caller ID. However, it does not mention side effects, authentication needs, or error handling.

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

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

The description is extremely concise, consisting of three clear sentences. It front-loads the purpose, then adds async behavior and defaults, and finishes with the optional parameter. Every sentence adds value with no redundancy.

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

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

Given the tool's complexity (6 params, async, no output schema), the description covers the essential aspects: purpose, input constraints, async nature, polling instruction, default mode, and caller identification. It lacks explanations of parameter formats (e.g., what constitutes a valid url or deck_text), but the mutual exclusion rule provides structural 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 only 17%, but the description compensates by explaining the mutual exclusivity of url/description/pitch_company_id/deck_text and the meaning of mode (defaults to deep) and requested_by (shown in activity feed). Some parameters lack detail, but the constraint is critical.

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: 'Assess one product's obsolescence risk.' It specifies the action (assess) and the target (product obsolescence risk), and distinguishes itself from siblings like get_assessment by noting async behavior and returning a job_id.

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 guidance on when to use the tool by requiring exactly one input from a set of alternatives. It also instructs to poll get_assessment for results, but does not explicitly exclude alternatives or state when not to use this tool.

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

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

No annotations are provided, so the description carries the full burden. It discloses key behavior: 'Fails closed if stale,' indicating a blocking failure mode. However, it does not detail what 'fail closed' entails or specify return values.

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 with no wasted words. Every sentence contributes useful information, making it easy for an agent to parse quickly.

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

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

Given the tool's simplicity (no parameters, no output schema), the description covers its role adequately. It mentions validation, staleness check, and the predecessor relationship to assess_product, providing sufficient context for its use in a 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?

The input schema has zero parameters, and schema coverage is 100%. The description does not need to add parameter information, and the baseline for 0 parameters is 4, which is appropriate here.

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 validates config and checks staleness of the roadmap-signals KB, with a specific verb-resource pair. It explicitly says 'Call before assess_product,' distinguishing its role from siblings like assess_product.

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 'Call before assess_product,' providing clear when-to-use guidance for a prep step. It lacks explicit when-not-to-use or alternatives, but the direct ordering is sufficient 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?

No annotations provided, so the description carries the full burden. It discloses the hard timeout behavior and that it never hangs on pending, which is valuable. However, it does not mention error handling, authentication needs, or rate limits, leaving gaps.

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 result, no wasted words. Structurally efficient and easy to parse.

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

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

Given the simple tool with one parameter and no output schema, the description covers the core purpose and a key behavioral trait. However, it omits input format details and error behavior, leaving room for improvement.

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

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

Schema coverage is 0%, so the description must explain parameters. It mentions 'assessment job_id' but does not elaborate on the format or origin of job_id. It adds some meaning but not enough to fully compensate for the lack of schema descriptions.

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 polls an assessment job_id, returns status and the typed assessment when complete. It uses specific verbs ('Poll', 'Returns') and resource ('assessment job_id'), distinguishing it from siblings like list_assessments and assess_product.

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 after an assessment job is created, but does not explicitly state when to use it versus alternatives or when not to use it. The 'Hard timeout' note provides behavioral guidance but no direct usage scenarios.

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

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

No behavioral details beyond listing and filtering; no mention of sorting, read-only nature, or pagination behavior. With no annotations, the description should disclose more.

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?

Extremely concise, front-loads purpose, no wasted words.

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

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

The description covers basic purpose and filtering, but lacks details on sorting, return format, or pagination behavior. With no output schema, more context would help.

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?

Adds meaning for verdict parameter as a filter, but limit parameter is not described. Schema has no descriptions, so description partially compensates.

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?

Describes listing assessments with filtering; clearly distinct from sibling tools like get_assessment (single) and assess_product (creation).

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 on when to use versus siblings; the usage is implied as listing recent assessments, but no alternatives 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?

No annotations are provided, so description carries full burden. It discloses operator-only access but does not cover other behavioral traits like read-only nature, rate limits, response behavior when no signals exist, or required permissions beyond operator role.

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?

Description is a single sentence plus a fragment, front-loaded with the primary action. Every word serves a purpose (listing, purpose of retirement, access restriction). 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?

Given no output schema, description should clarify return format beyond 'with their ids' (e.g., additional fields, pagination). Missing definitions of 'roadmap signal' and 'active (signed, grounding)'. Also lacks guidance on authentication or operator_key acquisition, which are critical for 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?

Schema has one required parameter 'operator_key' with 0% description coverage. Description adds 'Operator-only' as context but does not explain what operator_key is, its format, where to acquire it, or any constraints. This provides minimal semantic value 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?

Description clearly states the tool lists active (signed, grounding) roadmap signals with their IDs, and explicitly links to the use case of finding a signal_id to retire. This distinguishes it from siblings like list_signal_candidates and retire_signal.

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

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

Description directs use to finding a signal_id for retirement and restricts usage to 'Operator-only', providing clear context. It implicitly indicates when to use (before retire_signal) but does not explicitly state when not to use or mention 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?

With no annotations, description discloses operator-only restriction, default pending status, and lifecycle (approve/reject/sign). Does not mention pagination or return structure, but overall 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?

Two sentences, front-loaded with key phrase 'KB-refresh review queue', no redundant information.

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

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

For a list tool with no output schema and 3 parameters, description covers purpose, usage context, and basic parameter semantics. Lacks details on return format but sufficient for common use.

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?

0% schema coverage; description adds meaning by stating default status 'pending' (though schema lacks default) and implies operator_key is required. Does not explain limit or other status values.

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 clearly states it lists auto-scraped candidate roadmap signals from a KB-refresh review queue, with default status pending. It distinguishes from sibling tools by mentioning approve/reject with review_signal_candidate and cron signing.

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?

Specifies 'Operator-only' and connects to review_signal_candidate and weekly cron. Does not explicitly exclude alternatives like list_kb_signals, but provides clear context for when to use.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It indicates the tool is read-only and returns state metrics, but does not explicitly state safety (e.g., no side effects) or any authentication requirements. The term 'Inspectable State' implies no mutation, which is adequate but 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 short sentence with a clear front-loaded purpose ('Inspectable State'). It efficiently lists the returned components without unnecessary words.

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

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

Given the tool has no output schema and no annotations, the description is somewhat complete but lacks details on the format or structure of the returned data (e.g., whether results are lists or objects). It adequately conveys the general content but could be more informative.

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 zero parameters, so the description does not need to add parameter details. The baseline for 0 parameters is 4, and the description correctly notes 'No input'.

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 that the tool provides an 'Inspectable State' overview including counts, recent activity, roadmap-signal freshness, health, and last calibration run. It distinguishes from siblings like list_assessments or list_kb_signals, which are more specific, by being a broad summary.

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 provide any guidance on when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. It only notes that it requires no input.

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?

Describes the action as recording a calibration case, which implies a write operation. Notes operator-only access, but without annotations, the description carries full burden; it does not detail side effects or system impact beyond the weekly recalibration mention.

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

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

Three sentences with key information front-loaded. Every sentence adds value: purpose, access restriction, and parameter guidance. No redundancy or fluff.

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?

Covers core purpose, access, and parameter selection logic. Lacks explanation for enum values, optional parameters (notes, year_observed), and return behavior. Without output schema, the description should provide more on what happens after recording.

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 0% schema coverage, the description adds significant meaning: explains job_id vs product, operator_key restriction, and implicitly covers actual_outcome and expected_verdict. However, enum values remain unexplained and notes/year_observed are omitted.

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: recording actual outcomes for calibration cases. It uses a specific verb ('record') and resource ('outcome') and distinguishes from siblings by focusing on feedback rather than assessment.

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

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

Explicitly states precondition (operator-only, operator_key required) and parameter selection (job_id or product text). Implicitly indicates when to use (after assessment) but lacks negative guidance 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?

With no annotations, the description fully discloses behavior: soft-deletes (active=false), immediate effect on assessments, recoverable, operator-only requirement. Sufficiently transparent for a deletion-like operation.

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

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

One concise paragraph with front-loaded purpose. No wasted words. Could benefit from clearer structuring (e.g., separating purpose, parameters, usage notes).

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?

Covers core purpose, effect, and usage hint. Lacks parameter description details and return value information (no output schema). Adequate but leaves the agent to infer parameter meaning from 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 0%, yet the description provides only implicit meaning for parameters (e.g., operator_key for authorization, signal_id for target, reason for justification). No explicit formats, constraints, or examples for any 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?

Explicitly states the action (UNLEARN a KB signal) with specific examples (rumored feature cancelled, signal no longer predictive). Clearly distinguishes from sibling tools like list_kb_signals by referencing it for ID retrieval.

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

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

Provides clear usage context: signals that became false/obsolete. Notes operator-only restriction and points to list_kb_signals for finding IDs. Does not explicitly exclude other uses or name 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?

No annotations provided, so description carries full burden. It discloses the write operation, signing into KB, and dropping of rejected candidates. It mentions role-based access. However, does not state reversibility or side effects like whether approval is irreversible.

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

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

Three sentences, front-loaded with action and resource. No unnecessary words. Efficient and 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 mutation tool with 3 required params and no output schema, the description provides sufficient context: what it does, who can use it, and what happens after action. Could mention return values but not critical given no output schema.

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

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

Schema has 0% description coverage, so description must compensate. It mentions 'Operator-only' hinting at operator_key, and action is implied by the enum, but candidate_id is not described. The description adds some context but does not fully explain each parameter's meaning or format.

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

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

Description clearly states the action (approve/reject), resource (KB-refresh candidate signal), and outcome (signed into live KB or dropped). It distinguishes from sibling tools like list_signal_candidates by being a mutation. The verb and resource are specific and 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?

Explicitly states 'Operator-only', indicating a specific user role requirement. It implies usage context (deciding on candidates for KB refresh) but does not explicitly mention when not to use or alternative tools. However, given the sibling tools, the context is clear enough.

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

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

Describes the behavioral effect (active=false, stops scoring) and the intended workflow. With no annotations, this is good but could mention reversibility or side effects.

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

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

Two sentences with no wasted words. The key action ('UNLEARN') is frontloaded. Could benefit from bullet points for parameters.

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?

Adequate for a simple retirement action but lacks parameter descriptions and output details. The calibration domain context is assumed.

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?

Description does not explain the three parameters beyond their names. With 0% schema coverage, the agent gets no help on what values to provide for reason, case_id, or operator_key.

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?

Clearly states the tool retires a calibration case by setting active=false when labels are wrong or obsolete. Distinguishes from sibling record_outcome by describing a two-step workflow.

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

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

Explicitly states when to use (wrong/obsolete label), how to use (retire then record_outcome), and restrictions (Operator-only).

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