doom

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

The description discloses key behaviors: async execution, returns job_id, defaults to deep mode, and logging of requested_by in the activity feed. No annotations exist, so the description carries the full burden. It adds value beyond the schema, though it could clarify the behavior if multiple inputs are provided (despite the constraint).

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 at three sentences, each adding distinct value: purpose/constraint, async nature/polling, and defaults/optional parameter. It is front-loaded with the core purpose and avoids any extraneous text.

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

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

Given the tool's complexity (async, 6 parameters, no output schema), the description covers necessary context: mutual exclusivity, default mode, caller identification, and polling. It could elaborate on what 'quick' vs 'deep' mode entails, but overall it is sufficiently complete for an agent to invoke 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?

With only 17% schema description coverage, the description compensates well by explaining the mutual exclusivity of four parameters, the meaning of requested_by, and the default value for mode. It adds significant meaning beyond the schema's bare field names.

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 required input constraint ('Provide exactly ONE of description/url/pitch_company_id/deck_text') and distinguishes itself from siblings by mentioning async behavior and polling get_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?

The description gives clear usage guidelines: provide exactly one input, defaults to deep mode, and optionally pass requested_by. It implies when to use (starting an assessment) and mentions polling get_assessment for results, but does not explicitly state when not to use it or describe alternatives among sibling 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?

Discloses key behavior: validates config, checks staleness, and fails closed if stale. With no annotations, this covers essential traits, though lacks detail on exact failure output.

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: 3 short sentences, no filler. Every piece adds value and 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?

Adequately covers purpose, usage, and failure mode for a simple param-less tool. Missing specifics on 'config' and return value, but sufficient for the context.

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

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

No parameters exist, so schema coverage is 100% trivially. Baseline 4 applies; description adds no redundancy.

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 KB staleness, with a specific name 'Prep Gate' and explicit instruction to call before assess_product, distinguishing it from siblings.

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 'Call before assess_product', providing clear sequential usage guidance. No alternatives needed as it's a unique precondition step.

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 a hard timeout behavior and that it never hangs on pending, which is a key behavioral trait. No annotations exist, so the description carries the full burden—additional context like error handling would be beneficial but not critical.

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 key information. Every word adds value, with no 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?

For a simple polling tool with one parameter and no output schema, the description covers what it returns (status and typed assessment) and a key behavioral guarantee. It could mention error cases or the response format, but it is largely 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?

With 0% schema description coverage, the description must compensate but only mentions job_id without explaining its format, source, or constraints. The parameter is just a string, and the description 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 clearly states it polls an assessment job_id, returning status and the typed assessment when complete. It distinguishes the tool from siblings like assess_product (which initiates) and list_assessments (which lists).

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 starting an assessment, and the hard timeout guarantee is a guideline for when it is safe to use. However, it does not explicitly mention when to use vs alternatives like assess_product or list_assessments.

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, and the description does not disclose behavioral traits such as pagination, ordering, or what 'recent' means. Minimal 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?

Single sentence, no wasted words. Front-loaded, but could expand slightly without losing 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?

Fails to explain return structure, pagination, or definition of 'assessment'. Given 2 params and no output schema, description is insufficient for full understanding.

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 adds meaning to 'verdict' by mentioning filtering, but does not elaborate on valid values or behavior of 'limit'. Schema coverage is 0%, 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?

The description clearly states the tool lists recent assessments with an optional verdict filter. It distinguishes from sibling 'get_assessment' but could specify the scope of 'recent' more precisely.

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 'get_assessment' or other list tools. Lacks context for appropriate invocation.

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 must convey behavior. It mentions output includes IDs and that signals are active/signed/grounding. Lacks details on full output structure or side effects, but adequate for a simple listing 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?

Single sentence plus a fragment, no redundancy. Front-loaded with verb and resource. Every word serves a purpose.

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

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

For a simple list tool with one parameter, the description covers purpose, usage context, and access restriction. Missing details on return fields beyond IDs, but no output schema exists to fill that gap.

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

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

Schema coverage is 0% with no parameter descriptions. Description only loosely implies 'operator_key' is an authentication credential via 'Operator-only'. No format or example provided, leaving ambiguity about what value to pass.

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 active signed/grounding roadmap signals with IDs, and specifies its use case (finding a signal_id to retire). This distinguishes it from sibling tools like retire_signal and list_signal_candidates.

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' (who can use) and indicates usage scenario ('use to find a signal_id to retire'). However, it does not explicitly contrast with alternatives like list_signal_candidates or provide when-not-to-use guidance.

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

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

No annotations provided, so description must carry full burden. It implicitly indicates a read-only list operation, mentions auth requirement (operator-only), and describes the lifecycle. Lacks explicit statements about side effects or rate limits, but overall transparent.

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 front-loaded key information. Every sentence adds value: purpose, default behavior, auth, and lifecycle. 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?

Covers purpose, default, auth, and integration with sibling tools. Does not describe return format or error handling, but for a list tool with moderate complexity, this is sufficient.

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

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

Schema coverage is 0%, so description compensates by stating default status pending and contextualizing the tool's output. Operator_key explained via 'operator-only'. Limits inferred but not detailed.

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

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

Clearly states it lists auto-scraped candidate roadmap signals for KB-refresh review queue. Distinguishes from siblings by mentioning that approval/rejection is done via review_signal_candidate and signing by cron.

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 access, default status pending, and directs to review_signal_candidate for approve/reject actions. Lacks explicit exclusion of alternative tools like list_kb_signals but provides sufficient context for appropriate 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?

No annotations are provided, so the description carries full burden. It discloses that the tool is read-only ('Inspectable State') and requires no input, but omits behavioral details such as side effects, authentication needs, or response format. This is minimal 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, efficient sentence that lists the output components without redundancy. Every word is informative, achieving maximum 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 no parameters and no output schema, the description lists what the tool returns but lacks structural details (e.g., format of counts, definition of 'health'). It is adequate for a simple overview tool but leaves some ambiguity about the exact output shape.

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, and schema coverage is 100% (vacuously). The description does not need to add parameter information, earning a baseline score of 3. It adds no extra meaning beyond the schema.

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

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

The description states 'Inspectable State' and lists what it provides (counts, activity, freshness, health, calibration run), clearly indicating it returns a summary of system metrics. It distinguishes from sibling tools which focus on specific assessments or signal operations, though it could explicitly name the system being inspected.

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 it is a no-input read tool for obtaining an overall state summary, but does not explicitly state when to use it over siblings or provide any exclusion criteria. Usage guidance is implied through context.

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

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

No annotations exist, so the description carries the burden. It states operator-only requirement and that the record is folded into weekly recalibration, but does not clarify if the operation is destructive or has side effects (e.g., overwrites previous outcome).

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 and efficiently conveys purpose, access control, and key param relationship. The first sentence is slightly cryptic but overall compact.

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

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

With 7 parameters and no output schema, the description fails to explain enum values or optional fields like year_observed. The core purpose is clear, but parameter details are insufficient for an agent to invoke 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 0% with 7 parameters. Description adds context for job_id and product, but leaves other critical params (actual_outcome enum, expected_verdict enum, notes, year_observed) unexplained beyond basic names.

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 records actual outcomes for previously-assessed products as calibration cases, distinct from assessment tools. The verb 'record' and resource 'outcome' are specific, and it differentiates by focusing on feedback loop.

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

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

The description explains operator-only access and the need for either job_id or product text. However, it does not provide explicit when-to-use or when-not-to-use guidance compared to sibling tools like get_assessment or supersede_calibration_case.

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

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

With no annotations, the description carries full burden. It discloses the soft-delete action (active=false) and that it stops grounding assessments immediately, plus notes it is recoverable. This is good behavioral context, though it could elaborate on required permissions or error states.

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: the first explains purpose and examples, the second gives constraints and source for id. Every word is valuable, and 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?

Given no output schema, no annotations, and 3 parameters with 0% schema coverage, the description should be more complete. It explains the effect and recoverability but omits parameter details, response format, and potential errors. It covers core functionality but leaves significant gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'Find the id via list_kb_signals' for signal_id and implies reason via examples, but does not describe operator_key or provide format constraints. Two of three required parameters are only partially covered.

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 'UNLEARN's a KB signal that became false/obsolete,' with specific examples like a rumored feature cancelled. This verb+resource clearly distinguishes it from sibling tools like list_kb_signals.

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 context on when to use: signals that are false/obsolete. It also mentions 'Operator-only' as a prerequisite and instructs to find the id via list_kb_signals. However, it lacks explicit exclusions or mention of alternative tools, which are not needed given no direct sibling.

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

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

With no annotations provided, the description meaningfully discloses behavioral traits: approved candidates are signed (Ed25519) into the live KB on the next refresh, rejected ones are dropped, and it controls grounding truth. This goes beyond a simple verb and resource.

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 efficiently state the purpose and consequences, with no unnecessary words. Every part 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 (3 parameters, no nested objects, no output schema), the description covers the core behavior and outcomes. However, it omits details like what 'operator_key' validates or whether actions are reversible, leaving minor gaps.

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

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

Schema description coverage is 0%, so the description must compensate, but it does not explain the parameters beyond implying 'operator_key' is for operator authorization. The 'action' enum is clear, but 'candidate_id' and 'operator_key' lack semantic 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 clearly states 'Approve or reject a KB-refresh candidate signal,' providing a specific verb and resource. It distinguishes the tool's role in the KB refresh process, but does not explicitly differentiate it from siblings like 'retire_signal' or 'list_signal_candidates.'

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 mentions 'Operator-only' as a usage condition and explains the consequences of approval vs rejection. However, it lacks explicit guidance on when to use this tool versus alternatives (e.g., 'retire_signal' for removing signals), leaving the agent to infer 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 explains the core behavior (active=false, stops scoring) and access restriction (operator-only). However, it does not mention reversibility, side effects, or permissions beyond operator, but the main effect is well disclosed given no 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 sentences with no redundancy. The main action is front-loaded, and every word adds value.

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 operation and lack of output schema, the description covers the purpose, workflow, and constraints. Missing parameter details are a gap, but the overall context is sufficient for an operator to use the tool 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?

With 0% schema coverage for parameter descriptions, the description should compensate but does not explain operator_key, case_id, or reason beyond implicit understanding from names. This leaves ambiguity about format or purpose for 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 tool retires a calibration case by setting active=false, using the verb 'UNLEARN' and explicitly distinguishing its purpose from siblings like record_outcome. It specifies the resource (calibration case) and the effect (stops scoring).

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 guidance on when to use (label wrong or obsolete) and the correct sequence: retire then use record_outcome. It also restricts usage to operators only, setting clear boundaries against alternatives.

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