Scope (Claims) - Preview

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

Annotations already declare readOnlyHint=true, so safety is covered. Description adds bucketing and session-start context, but does not elaborate on auth or rate limits.

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 efficient sentences, front-loaded with key info: purpose, output format, usage guidance. No waste.

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?

Complete for a simple read-only tool with one parameter and no output schema. Explains what, returns, and when to use. No 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 covers the single parameter with description and constraints. Description confirms horizon_days controls completed-work bucket, adding no extra syntax or nuance.

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 verb 'Briefing' and resource 'authenticated org's recent matter activity', specifies output buckets. Distinguishes from siblings as cross-vertical read vs. domain-specific tools like scope_claims_* or scope_vendor_health.

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 advises using at session start to ground AI on changes. Lacks explicit when-not or alternatives, but context 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 indicate readOnlyHint=false and destructiveHint=false. The description confirms a write operation ('Join') but adds no further behavioral context beyond capturing firm and contact. Additional details like whether a confirmation is sent would improve 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?

Two short, clear sentences with no extraneous information. Every word is necessary and 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 2-parameter tool with no output schema, the description covers the action and inputs. However, it does not mention what happens after joining (e.g., response or confirmation), which could leave an agent wondering about side effects or return values.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description only says 'Captures a firm name and contact', adding no new meaning beyond the 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 uses the verb 'Join' and specifies the resource 'claims waitlist', clearly distinguishing the tool from siblings like scope_claims_status. The additional detail about capturing firm name and contact for the V2 cohort provides specific scope.

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 specify when to use this tool versus alternatives (e.g., scope_claims_status for checking status). No explicit guidance on prerequisites or when not 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?

Annotations already declare readOnlyHint=true. The description adds the context that this surface is Preview/waitlist until V2 launches, disclosing its developmental state. No contradictions.

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 with the verb and resource front-loaded. Every sentence adds value without 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 has no parameters and no output schema; the description explains its purpose and status. It could be slightly improved by hinting at the return format, but for a simple status check it is adequate.

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 provides complete coverage. The description adds no param details but none are needed; baseline 4 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 the action ('Returns') and the resource ('Scope claims server status'), and the 'Preview/waitlist' note differentiates it from sibling tools like scope_claims_join_waitlist.

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 the V2 launch timeline and the Preview/waitlist status, implying limited availability, but does not explicitly state when to use this tool versus its many siblings.

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

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

Annotations declare readOnlyHint=true, and the description consistently states 'Search'. It adds behavioral context: searches across every scope, case-insensitive substring match for party_name. No contradictions.

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 that are front-loaded with the action and scope, followed by use case and filter summary. Every sentence is necessary and 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 search tool with three parameters and no output schema, the description covers the purpose, filter options, and use case. It lacks hints about return format, but the completeness is adequate.

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 low (33%). The description adds meaning for 'party_name' (case-insensitive substring) and mentions 'optional lookback window' for 'since_days', but does not explain the unit (days) or the enum values for 'party_type'. It partially compensates but leaves 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 clearly states the action 'Search' and the specific resource 'carrier org's structured conflict-party log across every scope'. It distinguishes from sibling tools like 'scope_search_deliverables' by focusing on conflict-party log for prior-representation checks.

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 'Use for a prior-representation check before dispatching new work', providing clear context. It does not explicitly state when not to use or mention alternatives, but the use case is well-defined.

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=true. Description adds context on credential types but does not disclose other behaviors like output format or handling of no results.

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

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

Two concise sentences front-load the core purpose and sibling relationship with 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?

Provides essential filter context and sibling relation but omits details about output and parameter behavior; adequate for a simple tool but not fully complete.

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

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

Schema has 0% description coverage and description does not mention the days_ahead parameter, failing to explain its purpose or behavior.

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

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

Description clearly states it lists vendors with expiring/expired credentials (COI, W-9, insurance, BAA) and explicitly distinguishes itself from sibling tool scope_vendor_health as a filtered version.

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 context on when to use this tool (for credential alerts) and relation to scope_vendor_health, but lacks explicit when-not or alternative tool 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?

The annotations provide readOnlyHint=true, and the description adds value by disclosing that the returned download URL is short-lived, which is critical for agent decision-making. 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?

Two sentences, front-loaded with the verb 'Fetch', no wasted words. Efficiently communicates the core purpose and key output characteristic.

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 retrieval tool with good annotations and schema, the description adequately covers what it does and the important output detail (short-lived signed URL). No output schema exists, so the description compensates well.

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% (deliverable_id has a description). The tool description does not add further parameter meaning beyond what the schema provides, so it meets the baseline for high 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 uses the specific verb 'Fetch' and identifies the resource as 'vendor-uploaded deliverable by id', clearly distinguishing it from sibling tools like list or search. It concisely states the action and scope.

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 you need a specific deliverable by ID) but does not explicitly state when not to use it or mention alternatives like scope_list_deliverables_for_scope for listing. However, the context is clear enough for a simple fetch operation.

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=true. The description adds specific return fields (current state, vendor, timestamps, time remaining, bid count), which are beyond annotation scope.

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 wasted words, efficiently conveying the tool's purpose and output.

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?

Despite no output schema, the description lists key return fields, but could specify conditions or error handling for completeness.

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 description does not add extra meaning beyond the schema's 'UUID of the scope' for the single 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 'Read-only view of the roster auto-routing state machine for one claim/scope,' specifying the resource, action, and listed return fields, distinguishing it from sibling tools.

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

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

The description indicates it is for one claim/scope but does not provide explicit guidance on when to use this tool versus alternatives or when not to use it.

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

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

Annotations declare readOnlyHint=true, and the description adds value by detailing return fields, including secure-link URL (works without login) and short-lived signed download URL (1 hour TTL). No destructive behaviors, so transparency is good.

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 fluff. First sentence states purpose, second lists return fields. Front-loaded and efficient.

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 low complexity, the description is adequate but lacks information on pagination, ordering, or any limitations. No output schema exists, so the return field list helps, but completeness could be improved.

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% for the single parameter scope_id, so baseline is 3. The description does not add additional meaning beyond what the schema provides.

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

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

The description clearly states 'List vendor-uploaded deliverables for a scope' with specific verb and resource. It distinguishes from siblings like scope_get_deliverable (singular) and scope_search_deliverables by focusing on listing all deliverables for a given scope.

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 use for listing all deliverables for a scope but does not explicitly state when to use this vs alternatives like scope_get_deliverable or scope_search_deliverables. No exclusions or prerequisites are provided.

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

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

The description adds value beyond the readOnlyHint annotation by explaining the privacy gate condition (cohort_too_small) and the exact statistics returned. It does not cover all behavioral aspects (e.g., rate limits), but the annotation already covers safety.

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

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

The description is two sentences with no filler, front-loading the core function and quickly noting the privacy gate. Every sentence is essential.

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, the description adequately covers return values (stats and error case) and the main input parameters. It could mention parameter validation or response format, but is sufficient for the tool's complexity.

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

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

The description adds meaning for 'category' and 'jurisdiction' (linking them to the stats), but does not explain the 'sample_size' parameter. With schema coverage at 33%, the description partially compensates but leaves one parameter undocumented.

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 returns distribution statistics (min, p25, median, etc.) on awarded-bid amounts for a service category, with optional jurisdiction. This specific verb+resource combination distinguishes it from sibling tools which cover different domains (claims, deliverables, etc.).

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 clear context for when to use the tool (market rate comparison) and notes a privacy constraint (cohort size gate). It does not explicitly state when not to use it or mention alternatives, but the sibling list implies differentiation.

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 behavioral context beyond annotations by noting it returns an 'append-only event chain,' which implies immutability. Annotations already declare readOnlyHint=true, and the description reinforces this without contradicting.

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 that front-load the primary purpose and follow with usage context. No 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?

For a simple read tool with 2 parameters and no output schema, the description adequately covers the return type (event chain) and use cases. It lacks details about pagination or default behavior but remains 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?

Only 50% of parameters have schema descriptions (scope_id has a brief 'UUID of the scope' description, limit has none). The description does not clarify limit's meaning or provide additional details for either 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 it returns a complete activity log for a scope, specifying it's an append-only event chain. This distinguishes it from sibling tools like scope_briefing or scope_claims_status which serve different purposes.

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 states usefulness for compliance review or matter-record export, indicating appropriate contexts. However, it does not provide explicit when-not-to-use guidance or alternative 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?

The description adds the implementation detail 'v1 uses SQL ILIKE on notes + deliverable_type', which is beyond the readOnlyHint annotation. However, it does not disclose potential limitations like performance implications or scope_id behavior, leaving gaps in 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?

Two sentences with no wasted words. The first sentence states the purpose, the second provides implementation context. Front-loaded and efficient.

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?

Despite having 3 parameters and no output schema, the description fails to explain the role of scope_id, the format of deliverable_type, or any search result behavior. It is too sparse for a search tool with optional filters.

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 partially addresses parameters. It mentions 'query' and 'deliverable_type' in context of ILIKE search, but does not explain 'scope_id' at all, leaving a key parameter ambiguous.

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 'Search the carrier org's deliverables by free-text query', which is a specific verb-resource pair. It distinguishes from siblings like scope_get_deliverable (get by ID) and scope_list_deliverables_for_scope (list all) by indicating a search capability.

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 on when to use this tool versus alternatives. It does not mention the differences from sibling tools like scope_list_deliverables_for_scope or scope_get_deliverable, nor does it give conditions for 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?

Annotations already indicate non-read-only and non-destructive behavior. The description adds that it sends across specific channels but does not detail side effects (e.g., whether duplicate sends are prevented) or concurrency implications. Adequate but could be more informative.

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 the core purpose and key constraints (channels, carrier org). No wasted words; front-loaded with the action and resource.

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 three required parameters, no output schema, and minimal annotations, the description provides a basic understanding but lacks details on return values, prerequisites (e.g., deliverable existence), error conditions, or success confirmation. It is minimally sufficient but not fully comprehensive.

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 compensate. It lists the allowed channels, helping with the 'channels' parameter, but does not describe the structure of 'recipients' (kind, value) or 'deliverable_id'. The parameter meanings are largely unexplained, leaving the agent with insufficient guidance.

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 action ('Ad-hoc re-send of an existing deliverable') and resource ('deliverable'), specifying it is for additional recipients across multiple channels. This distinguishes it from sibling tools like 'scope_get_deliverable' or 'scope_list_deliverables_for_scope' which are read-oriented.

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 notes that this is for re-sending to additional recipients, implying it is not for initial sends. It also restricts usage to 'Carrier org members only'. However, it lacks explicit guidance on when not to use it or alternative tools for initial sends.

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

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

Annotations already declare readOnlyHint=true, so the description adds value by specifying the scope ('across the carrier org') and the time window behavior, which are not captured in structured fields. No contradictions.

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 (19 words total) front-load the core action and grouping options with zero wasted words. Ideal for quick parsing by an AI agent.

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 tool with no output schema, the description covers purpose and parameters adequately. It lacks mention of return format (e.g., aggregated sums) but is sufficient given low complexity and annotation support.

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 compensates by explaining that 'days' sets the date window and listing the five enum values for group_by, mapping directly to schema properties. However, it does not explain the default values or provide examples.

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 'Aggregate awarded-bid spend across the carrier org over a date window' with a specific verb+resource, clearly distinguishing it from sibling tools like scope_vendor_health or scope_market_rate_compare, which serve different purposes.

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 this tool versus alternatives. The description does not mention scenarios for exclusion or suggest other tools for different grouping needs, leaving the agent to infer usage 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 readOnlyHint=true, and the description adds context about what is covered (credential, insurance, BAA, on-time status) and vertical relevance. However, it does not elaborate on data freshness, pagination, or limitations beyond the annotation.

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

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

The description is concise with two sentences. The first sentence densely packs the tool's coverage, and the second adds relevant vertical context. No 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?

For a simple read-only report tool with one parameter, the description adequately states purpose and relevance but lacks output schema details and parameter explanation. Given no output schema, the description should describe return format, which it does not.

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

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

The input schema has one parameter 'days_ahead' with default 30 and constraints, but the description does not mention or explain it. Schema description coverage is 0%, and the description fails to compensate, leaving the parameter's purpose ambiguous.

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 provides per-vendor credential, insurance, BAA, and on-time status across the roster, with specific mention of HIPAA BAA relevance for claims vertical. This distinguishes it from siblings like scope_credential_alerts, which likely focus only on credentials.

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 for checking vendor health report, especially for HIPAA BAA in claims vertical, but does not explicitly state when to use vs alternatives or when not to use. No sibling comparisons are provided.

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