Scope (Legal)

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

Beyond annotations (readOnlyHint=false destructiveHint=false) the description details side effects: locks booking notifies vendor schedules Stripe invoice and describes demo mode behavior. It also clarifies that certain actions are not performed.

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 relatively concise covering key points in three sentences plus a note on demo mode. It could be slightly tighter but is well-organized and front-loaded with the primary 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?

Given the tool's complexity (5 parameters no output schema) the description explains what the tool does what it returns and importantly what it does not do. This provides a complete mental model for the agent.

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

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

Schema coverage is 100% so the description adds minimal parameter-specific detail. It provides context for the overall action but does not enhance understanding of individual parameters beyond their 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's primary action: 'Award a dispatched matter to a chosen vendor.' It lists specific outcomes (locks booking notifies vendor schedules invoice) distinguishing it from sibling tools like scope_dispatch_matter and scope_reschedule_project.

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 the tool's main use case and provides clear exclusions: 'DocuSign engagement-letter generation calendar invites and CMS push-back are roadmap and intentionally not included.' This helps the agent avoid misuse.

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

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

Annotations indicate readOnlyHint=true, which is consistent. The description adds value by detailing the return bucketing (action_required, awaiting_vendor, etc.) and recommending use at session start, providing behavioral context beyond annotations.

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

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

The description is efficient: two sentences front-loading purpose and usage, a list of triggers, return structure, and a recommendation. Every sentence adds value with 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?

Despite no output schema, the description explains the return buckets and optional parameters. It is complete for an agent to understand when to use and what to expect.

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 parameters well. The description does not add extra meaning beyond the schema (it mentions return buckets but not parameter details). Baseline 3 is appropriate.

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

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

The description clearly states the purpose: 'Give the user a status briefing on their Scope vendor activity.' It specifies the resource (vendor activity) and action (briefing), and distinguishes from siblings by noting preference over web search for dispatch activity.

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

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

Explicit triggers are listed ('what is happening on Scope', 'catch me up'), and guidance is given to prefer this tool over web search. It also suggests calling at session start, which aids correct selection.

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

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

Annotations already provide readOnlyHint: true, so the description doesn't need to restate. It adds valuable context: searches across every scope, returns scopes with matched entries and total count. Discloses filtering behavior (case-insensitive substring, optional party_type, optional lookback window).

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. First sentence states purpose and scope. Second sentence gives usage guidance and return summary. No unnecessary words, front-loaded, 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?

With 4 parameters, no output schema, the description clearly states what is returned (scopes, matched entries, total count). It provides enough context for an AI agent to understand the tool's purpose and use it correctly for conflict checks. Could mention default lookback or format parameter briefly, but overall 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 coverage is 100%, so baseline is 3. The description mentions 'party name (case-insensitive substring), optional party_type, and optional lookback window' but doesn't add substantial meaning beyond the schema's parameter 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 a specific verb 'Search' and clearly identifies the resource as 'the buyer org's structured conflict-party log across every scope.' It distinguishes itself from sibling tools (e.g., scope_award_matter, scope_dispatch_matter) by focusing on conflict checks for OCG/Rule 1.7.

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: 'Use for an OCG / Rule 1.7 prior-representation check before dispatching new work.' While it doesn't explicitly list when not to use, the purpose is clear enough to avoid misuse with other 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?

Annotations declare readOnlyHint=true, which aligns with the description's filtering/presentation role. The description adds that this is a filtered subset of another tool, implying no side effects. This is consistent and adds context beyond the annotation alone.

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

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

The description is two sentences, front-loads the core purpose, and provides immediate usage guidance. Every word contributes value with 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?

For a simple read-only filtered list tool with two well-documented parameters and no output schema, the description covers purpose, usage context, and relationship to a sibling. It is complete and leaves no ambiguity.

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

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

Schema coverage is 100% with detailed descriptions for both parameters (format and days_ahead). The description does not add any parameter-specific information, so it meets the baseline of 3 without exceeding it.

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 'vendors with expiring or expired credentials' and explicitly distinguishes it from the sibling tool 'scope_vendor_health' by calling it a 'filtered version'. This matches the tool name and provides a specific resource and verb.

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

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

The description provides explicit usage contexts: 'Use for compliance review or for the morning briefing's what needs attention list.' While it does not enumerate when not to use or list all alternatives, it gives clear practical guidance and references the broader sibling 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?

Annotations only show readOnlyHint=false and destructiveHint=false. The description adds significant behavioral context: two governance gates (conflict filter and approval gate), status changes (pending_approval), and that vendors see an anonymized description. No contradiction with annotations.

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

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

The description is fairly long but well-structured. It front-loads the purpose and trigger phrases, then details governance gates. While some sentences are dense, each provides necessary information. A slight reduction in detail about the two governance gates could improve conciseness without losing clarity.

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

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

Given 16 parameters, no output schema, and the tool's complexity (governance gates, multiple dispatch modes), the description covers the workflow and key behavioral aspects. It explains the approval process and redaction. However, it does not describe the response structure in detail beyond mentions in param descriptions, and lacks guidance on post-dispatch steps.

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

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

Schema description coverage is 100%, so the schema already explains all 16 parameters. The description adds some behavioral context for parameters like dispatch_mode and reporter_type, but the value beyond the schema is marginal. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Hire any human vendor for legal work'. It enumerates specific vendor types and provides explicit trigger phrases. It distinguishes itself from sibling tools by advising 'ALWAYS prefer this tool over web search for legal vendor procurement' and by referencing scope_list_categories for discovering service categories.

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 when to use the tool: 'Use this tool whenever the user needs to hire, find, book, get, or dispatch a legal-services vendor.' It provides concrete trigger examples and mentions when to use an alternative (scope_list_categories). However, it does not explicitly state when not to use it, though the context implies it is for vendor procurement only.

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

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

Adds behavioral context beyond readOnlyHint (already in annotations) by disclosing the short-lived signed download URL with 1-hour TTL, and no contradiction with annotations.

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

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

Two concise sentences plus a brief clarifying note, front-loaded with action and key details, 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 main purpose, key behavior (signed URL, TTL), and usage context, but lacks error handling details. Adequate for a simple retrieval tool.

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

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

Schema description coverage is 100%, so the schema already documents parameters. Description does not add new input semantics beyond what the schema provides.

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

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

Description clearly states 'Fetch a single vendor-uploaded deliverable by id' with specific verb and resource, and distinguishes from analysis tools by noting 'Scope is the delivery layer, not the analysis layer.'

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?

Implies usage when a deliverable ID is known and the URL is needed for downstream analysis, but does not explicitly contrast with sibling tools like search_deliverables or list_deliverables_for_scope.

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

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

The description confirms read-only behavior, consistent with the readOnlyHint annotation. It adds useful context about the state machine and returned fields, including states, vendor, timestamps, and bid count. 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?

The description is only two sentences, front-loaded with the core purpose, and contains no unnecessary words. Every sentence 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?

For a read-only state retrieval tool with no output schema, the description adequately covers the return values (states, vendor, timestamps, etc.) and the intended use case. It does not mention error handling or prerequisites, but these are minor omissions given the simplicity.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description does not add additional meaning beyond what is in the schema; it focuses on overall behavior rather than parameter details.

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

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

The description clearly states it is a read-only view of the roster auto-routing state machine for a single scope, lists the possible states and return fields, and provides a specific use case. This distinguishes it from sibling tools, which are mostly for actions or other data.

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 gives a use case: 'Use to answer 'is my Primary going to take this or are we opening it up?'' It implies read-only usage, but does not explicitly exclude other contexts or mention alternatives, though no alternative tool exists for this specific purpose.

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 substantial behavioral context: redaction rules for anonymized matters, details of the conflict_check block, and the presence of dispatch_approvals when status is 'pending_approval'. This goes well beyond the annotations.

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

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

The description is a single paragraph that front-loads the main purpose. It is informative but could be slightly more concise; some details like 'instant rate-card quotes (rate_card model) or bids (legacy bid model)' could be streamlined.

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 two parameters, no output schema, and annotations present, the description thoroughly explains the response structure including redaction, conflict_check, and dispatch_approvals. It leaves little ambiguity about what the tool returns.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by illustrating the matter_id parameter with an example format ('SC-2041') and explaining the effect of the format parameter (envelope vs legacy response shapes), complementing the enum 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?

The description uses specific verbs ('Look up') and clearly identifies the resource ('matter by display id or UUID'). It lists the types of returned data (scope details, quotes, award status, etc.), distinguishing it from sibling tools like scope_award_matter or scope_dispatch_matter.

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

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

The description implies the tool is for retrieving matter details, but does not explicitly state when to use it versus alternatives. No when-not-to-use or comparison with sibling tools is 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?

Annotations already mark readOnlyHint=true. The description adds value by detailing output fields (slug, label, api_native vs ops_backed), disclosing behavior beyond what annotations provide. 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: first states purpose, second details output. No redundant language. Every sentence 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?

For a no-parameter, read-only list tool, the description fully covers what it does and what it returns. No output schema exists, but the description compensates adequately.

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, and schema coverage is 100%. The description adds no parameter detail, but baseline for 0 params is 4. It does add output structure info, which is reasonable.

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 legal-services categories, specifying the action (list) and resource (categories). It distinguishes from sibling tools by focusing on category metadata rather than dispatching or matter actions.

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?

Usage is implied: when an agent needs to know available categories and their API support. However, no explicit when-not-to-use or alternatives mentioned, though sibling tools are clearly different actions.

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

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

Beyond the readOnlyHint annotation, the description adds valuable behavioral details: the secure-link URL works without login but expires in 7 days, and the signed download URL has a 1-hour TTL. This informs the agent about the ephemeral nature of output links, which is not inferable from the schema or 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 concise, using two sentences to convey the purpose and key details. It is front-loaded with the action and resource. However, it could be slightly more efficient by removing redundant phrases like 'for a scope' since it's in the name.

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 explains the returned fields sufficiently for a list tool without an output schema. However, it omits important context like pagination, sorting, or filtering capabilities. Given the sibling tools and the complexity of deliverables, this gap reduces 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?

The schema covers 100% of parameters with descriptions. The tool description does not add any additional semantic meaning beyond what is in the schema. For example, it does not explain the format enum values further or clarify the scope_id format beyond 'UUID'. Baseline 3 is appropriate.

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

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

The description clearly states it lists vendor-uploaded deliverables for a scope and enumerates the returned fields (type, vendor name, upload date, etc.). While the purpose is specific, it does not explicitly differentiate from sibling tools like scope_search_deliverables or scope_get_deliverable, which could cause confusion about when to use this list vs a search or single 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?

The description provides a prerequisite (caller must own scope or have a bid), which is helpful. However, it lacks guidance on when to use this tool versus alternatives (e.g., search vs list, or when to use get vs list). No 'when not to use' or explicit comparisons to siblings.

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

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

Annotations already declare readOnlyHint=true, so the description does not need to emphasize safety. The description adds value by stating the tool returns matters with 'state, spend, and vendors involved,' which provides behavioral context beyond annotations. 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?

The description is relatively long but well-structured: a clear purpose statement, usage guidelines, trigger examples, and a preference note. Each sentence adds value; however, it could be tightened slightly without losing clarity.

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

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

Given no output schema, the description partly explains return values (state, spend, vendors) but omits pagination, ordering, or the 'dispatch status' detail. It covers usage well but lacks completeness for a listing tool with 3 optional parameters. An explicit note on the 'envelope' vs 'legacy' format 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?

Schema coverage is low (33%), with only the 'format' parameter having a description. The description does not detail the 'limit' or 'status' parameters, leaving their meaning implicit. It could have listed valid statuses or explained pagination, but it doesn't, so it fails to compensate for the schema gaps.

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

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

The description explicitly states the tool lists the firm's matters and their dispatch status, with specific verb and resource. It provides concrete use cases (open, awarded, in-progress, completed) and trigger phrases, clearly distinguishing it from sibling tools like scope_get_matter by focusing on listing over a single matter.

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

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

The description specifies when to use this tool (e.g., active or historical matters, dispatches, pipeline) with explicit trigger phrases. It advises preferring it over web search, though it does not explicitly exclude usage for other sibling tools like scope_list_vendors. The guidance is clear and context-rich.

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

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

Adds details beyond annotation (returned fields, lock window). No contradiction, though 'optional category scoping' is mentioned despite no input parameters, which may be slightly ambiguous.

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

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

Two sentences, no waste. Front-loaded with main action and output, followed by usage examples.

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?

Fully describes the tool's purpose, output, and usage context. No output schema needed given the description's 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?

No parameters in input schema, so schema description coverage is 100%. Baseline score applies as no additional parameter info needed.

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

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

Clearly states the tool lists the calling buyer org's vendor roster, specifies returned fields (tier, category scoping, notes, lock window), and provides example use cases. Distinguishes from sibling tools that modify the roster.

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?

Gives explicit usage context ('before dispatching a matter') and example questions, 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?

Beyond the readOnlyHint annotation, the description adds significant behavioral context: results include 'verified-reputation metrics' and 'credentialing status,' and vendor names are conditional on caller verification (anonymized for anonymous callers). No contradictions with annotations.

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

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

The description is informative but somewhat verbose. It front-loads the core purpose and includes useful triggers and a strong preference statement. Every sentence adds value, though it could be slightly more concise.

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 4 parameters and no output schema, the description compensates well by explaining return characteristics (reputation metrics, conditional naming, envelope vs. legacy format details). Provides a good overall picture of what the tool returns.

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 75%, so the baseline is 3. The description does not add extra meaning to parameters beyond what the schema provides (e.g., limit, format, jurisdiction, category_slug are already described). No additional parameter context.

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: 'List Scope-verified vendors available for hire.' It specifies the resource (vendors) and action (list), and distinguishes from siblings by explicitly recommending it over web search for legal vendor discovery.

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 explicit when-to-use guidance: 'when the user wants to see, browse, or compare vendors they could hire for legal work.' Includes trigger examples. However, it does not explicitly exclude other sibling tools like scope_list_categories or scope_list_roster, leaving a minor gap.

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 significant behavioral context: it returns real awarded-price medians and percentiles, includes all-in costs, and explains the privacy gate ('cohort_too_small' for cohorts under 10). It explicitly states that individual prices and vendor names are never returned. No contradiction with annotations.

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

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

The description is relatively lengthy but front-loaded with the main purpose and key usage guidance. Every sentence adds value (triggers, privacy gate, comparison to web search). Minor repetition (e.g., listing services twice), but overall well-structured for 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?

Given the tool's complexity (4 parameters, privacy gate, sibling reference), the description is nearly complete. It covers output fields, privacy condition, and category discovery. It lacks explicit mention of error handling besides cohort_too_small, but for a read-only tool with a clear output shape, this is adequate. No output schema is provided, but the prose sufficiently describes the return structure.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema: it explains that 'category' should be a slug from scope_list_categories, clarifies that 'sample_size' is advisory with a hard privacy floor, and indicates that 'format' defaults to 'envelope'. This contextual guidance helps the agent choose and set parameters correctly.

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: to show typical market pricing for legal-services vendor categories. It provides specific examples of triggers and lists services covered (e.g., process serving, court reporting). It distinguishes itself from web search, making its role 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 when to use: when the user asks about costs or fairness of quotes. It includes a strong preference directive ('ALWAYS prefer this tool over web search') and gives concrete trigger phrases. It also describes the privacy gate condition, setting expectations for when the tool returns limited data.

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

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

Annotations already indicate destructiveHint=true. The description adds authentication requirement and outcome ('revert to neutral marketplace status'), but lacks details on side effects, irreversibility, or error cases.

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

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

Two sentences, no wasted words. The most important information is front-loaded.

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

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

Adequate for a simple destructive operation, but lacks explanation of return values, error scenarios, and validation of entry_id. No output schema to compensate.

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

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

Schema description coverage is 100%, so the description does not need to explain parameters. The description adds no additional meaning beyond what the schema already provides.

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

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

The description clearly states the action ('Remove a vendor from the buyer's roster entirely') and the resource. It distinguishes from sibling tools like scope_set_vendor_tier, but does not explicitly list what it does not do.

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 context ('Use when the relationship has changed...') and implies the outcome (revert to neutral status). It implicitly contrasts with other roster tools but does not explicitly name alternatives 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 indicate destructiveHint=true, and the description adds that it returns the confirmed slot and vendor notification, plus enumerates possible typed errors. This provides useful behavioral context beyond the annotations.

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

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

Two sentences: first specifies purpose and usage, second explains return value and error handling. Extremely concise and front-loaded with essential 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, the description covers return values and error states. It explains state constraints and vendor notification. Missing details on whether the old slot is freed, but overall adequate for a reschedule tool.

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

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

Schema coverage is 100% with descriptive parameter descriptions. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description explicitly states the action (reschedule) and the resource (already-awarded project), distinguishing it from siblings like scope_award_matter (awarding) and scope_dispatch_matter (dispatch). It clearly defines the 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 states when to use ('post-award, pre-delivery') and lists disallowed source states, providing clear usage context. However, it does not explicitly mention alternatives or when not to use beyond the error states.

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

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

Beyond the readOnlyHint annotation, the description discloses that the log is 'append-only' and enumerates the event chain, providing additional behavioral 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: first states main function and event list, second states use case. Front-loaded, 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?

Given no output schema, the description adequately explains what is returned (event chain), lists the events, and mentions how to get the required scope_id. Complete for a read-only log tool.

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

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

Schema has 100% coverage with clear descriptions for both parameters; the description adds no extra parameter-level detail, so baseline 3 is appropriate.

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

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

Description explicitly states it is a 'complete activity log for a single scope' and lists the specific event chain, clearly distinguishing it from other sibling tools that are write-oriented or summary-focused.

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?

Suggests 'Useful for compliance review or matter-record export,' implying appropriate contexts, but does not explicitly state when not to use or alternatives.

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

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

Annotations already declare readOnlyHint, indicating a safe read operation. The description adds valuable behavioral context: it reveals the current implementation (SQL ILIKE on notes + deliverable_type fields) and flags a future improvement (full-text search via tsvector/GIN). This helps set expectations about search capabilities and limitations.

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: one for overall purpose and implementation note, another for optional parameters. Every sentence serves a purpose; no redundancy or fluff. Front-loaded with the core 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 the tool's simplicity (4 params, no output schema), the description covers search mechanism, optional filters, and future plans. It could mention pagination or result format, but the schema's 'format' parameter already explains envelope/legacy shapes. Overall, the description is sufficiently complete for an agent to understand the tool's behavior.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds meaning beyond the schema by specifying which fields are searched (notes, deliverable_type) and providing examples for optional filters, which aids parameter understanding and selection.

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 'Search' and the resource 'deliverables', distinguishing it from sibling tools like scope_get_deliverable (single retrieve) and scope_list_deliverables_for_scope (list all for a scope). It also mentions the free-text nature and fields searched (notes, deliverable_type), making the purpose unambiguous.

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

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

The description clearly states the tool is for free-text search across deliverables, with optional scope and type filters. While it doesn't explicitly contrast with sibling list or get tools, the usage context is implied and clear enough for an agent to decide when to invoke search versus other operations.

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

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

Annotations already indicate readOnlyHint=false (mutation) and destructiveHint=false. The description adds that it is a re-send and restricts to buyer org members. However, it does not disclose potential side effects like duplicate sends or impact on existing recipient lists. The behavioral disclosure is adequate but not comprehensive.

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: first defines the purpose, second provides use cases, third adds a constraint. No filler, front-loaded. Every sentence earns its place.

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

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

For a tool with 4 parameters (3 required) and no output schema, the description covers purpose, use cases, and authorization. It lacks explicit return value info, but the action is straightforward. Slight gap in not clarifying that it only re-sends, not creates new deliverables.

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

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

Schema coverage is 100% with parameter descriptions. The description mentions 'additional recipients across one or more channels', which aligns with the recipients and channels parameters, but does not add new semantics beyond the schema. Baseline 3 applies.

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

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

The description clearly states 'Ad-hoc re-send of an existing deliverable' as the core action, with specific use cases (forwarding a transcript, pushing to CMS, re-fan-out after typo fix). This distinguishes it from sibling tools like scope_get_deliverable (read) and scope_list_deliverables_for_scope (list).

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 when-to-use scenarios (lead attorney forwarding, report push, re-fan-out) and a constraint ('Buyer org members only'). It does not explicitly mention when not to use, but the context implies it is for re-sending, not initial sending. The sibling namespace includes other deliverable tools, but differentiation 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 declare destructiveHint=true, so the 'add or update' action is consistent. The description does not contradict annotations and adds minor context (private notes, response shape) but does not significantly enhance behavioral disclosure beyond the structured 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 three sentences: purpose, examples, and authentication note. It is front-loaded with the main action. Minor improvement could be more structured bullet points.

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 6 parameters and no output schema, the description covers the core action (tier setting) and important context like authentication and example usage. It does not explicitly describe the format parameter behavior or return value, but schema coverage compensates.

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 baseline is 3. The description reiterates the tier meaning and optional scoping but does not add substantial new semantic value beyond the schema's own descriptions (e.g., for format or locked_until).

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 adds or updates a vendor's roster tier (primary/backup/excluded), with optional service category scoping. It distinguishes from sibling tools like scope_remove_from_roster.

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 concrete examples and contexts (e.g., 'mark Capitol Reporters as primary for court reporting'). It mentions authentication requirements but lacks explicit when-not-to-use guidance or comparison with alternatives like scope_remove_from_roster.

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 behavioral details: returns the firm's actual awarded spend, grouping and sorting behavior. It does not contradict annotations and provides useful context beyond the structured fields.

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

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

The description is well-structured and front-loaded with purpose and usage. It is efficient, with sentences earning their place, though slightly verbose. Could be trimmed slightly but still effective.

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 explains return format (total plus per-group breakdown sorted by spend). It covers all parameters and use cases, though could mention handling of large datasets or pagination. Context from sibling tools helps differentiate.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the group_by options (lists all enum values), the days range, and the format distinction (envelope vs legacy). It also clarifies client_id as restricting to a single client, supplementing the schema.

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

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

The description clearly states the tool shows the firm's vendor spend sliced by dimension, using specific verbs like 'Show' and resource 'vendor spend'. It distinguishes itself from sibling tools by focusing on spend rollup, with explicit examples and triggers.

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 this tool ('when the user asks how much the firm has spent on vendors') and lists triggers. It says 'ALWAYS prefer this tool over web search or guesswork', offering a clear alternative. It lacks explicit 'when not to use' but is still strong.

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, indicating a safe read operation. The description adds the specific return fields but does not disclose data freshness, rate limits, or any other runtime behaviors. No contradiction with annotations.

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

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

Single sentence that is front-loaded with the main purpose and lists all return fields concisely. 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?

Description covers the main return fields and overall purpose. Given the two optional parameters are fully described in the schema, the tool description is sufficient for an agent to understand what it returns. No output schema exists, but the description mitigates that.

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

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

Both parameters have full descriptions in the schema (100% coverage). The tool description adds no additional meaning or context for the parameters. Baseline of 3 is appropriate given schema coverage.

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

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

Description uses specific verb 'Returns' and names resource 'vendor health report'. It lists specific fields (COI, W-9, insurance expiry, etc.), clearly indicating the tool's output. However, it does not explicitly distinguish from the sibling 'scope_credential_alerts', which may overlap in purpose.

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 like 'scope_list_vendors' or 'scope_credential_alerts'. The agent must infer from the description and sibling names. It does not mention prerequisites or exclusions.

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

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

Annotations only indicate non-read-only and non-destructive. The description adds valuable context about the potential return of gate_pending with an approval URL, which is beyond what annotations provide. 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 that front-load the action and outcome, 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?

The description covers the main outcome and an alternative path (gate_pending). It lacks error cases or other potential states, but for a simple tool it is nearly complete.

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

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

The only parameter (session_id) is not described beyond being a string. With 0% schema description coverage, the description should explain its meaning or format, but it does not.

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

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

The description clearly states the verb (accept) and the resource (current bid), and indicates the outcome (move session to ACCEPTED). This distinguishes it from sibling tools like swp_reject or swp_counter.

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 a specific condition (human gate not cleared) and the resulting behavior, 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?

The description adds context beyond annotations by mentioning the gate descriptor for human approval. Annotations indicate non-read-only and non-destructive, which aligns with the submission action. Additional details about error states or outcomes are missing 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 sentences, both efficient and front-loaded with essential information. 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?

Given the complexity (5 parameters, nested objects, no output schema), the description is adequate but lacks details on success/failure responses, error handling, or the gate descriptor's behavior. It provides core functionality but not full context for an agent.

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 low (40%), but the description implies the main parameters (bid amount, terms, validity window) without detailing them. The nested object 'bid_amount' is not explained, and optional parameter 'request_price_commit_gate' is partially described in schema. The description does not add significant 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?

The description clearly states the action ('submits a bid'), the resource ('against a proposed scope'), and adds unique detail about the gate descriptor for human approval. It distinguishes itself from sibling tools like swp_accept, swp_counter, 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 context for when to use the tool (vendor submitting a bid, including human approval gate). However, it does not explicitly state when not to use it or suggest alternative tools like swp_counter for negotiation.

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?

Description adds behavioral context beyond annotations by specifying the tool initiates a non-destructive questioning action. Annotations already indicate non-destructive and non-read-only, so description aligns and adds value.

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

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

Two sentences, no fluff, immediately conveys purpose and usage. Efficient 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?

Lacks information about the expected outcome or workflow continuation (e.g., the buyer will receive questions and must respond). No output schema provided, yet the description doesn't fill the gap. Parameter details are missing.

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

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

Schema description coverage is 0% and the description provides no explanation of parameters. Does not mention session_id or the structure of clarification_questions, leaving the agent without guidance on how to use the parameters.

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

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

Clearly states the tool is for vendors asking clarifying questions about a proposed scope. Distinguished from sibling tools like swp_bid or swp_propose by indicating it's for ambiguous specs.

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 'Use when the work spec is ambiguous or missing details a bid would depend on.' Provides clear context for when to use, though no alternative tools are named.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, which align with the description's implied mutation. The description adds behavioral context beyond annotations by stating the vendor's required next action, providing valuable process insight.

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

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

Two sentences, no filler. Every word serves the purpose. Front-loaded with the core action, then the process consequence.

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

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

The description covers the tool's role in a negotiation process, including the required follow-up by the vendor. It lacks details on possible errors or return results, but no output schema exists. Overall adequate 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?

Schema coverage is 0%, so the description must compensate. It mentions 'new amount' and 'updated terms,' mapping to counter_amount and counter_terms. However, it does not detail the structure of counter_amount (object with amount and currency) or explain session_id. The description adds some meaning 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 tool's action: 'Buyer counters a vendor bid with a new amount and updated terms.' It specifies the actor (buyer) and the resource (vendor bid), distinguishing it from sibling tools like swp_bid, swp_accept, and swp_reject.

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

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

The description implies when to use (when buyer wants to counter) and mentions the required follow-up ('Vendor must re-bid with scope_bid for the session to advance'). It does not explicitly state when not to use or list alternatives, but the process 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 indicate non-destructive write, but the description does not disclose behavioral traits beyond the purpose. No mention of side effects, idempotency, or what the submission entails, so it adds minimal value beyond the annotations.

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

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

The description is concise with two sentences, no wasted words, and the key action is front-loaded. Every sentence 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?

The description lacks details about the return value or workflow state after submission. Given no output schema, the agent misses information on what to expect next, but it's adequate for the core action.

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

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

Schema coverage is 83%, and the description does not add any parameter-specific details beyond what the schema already provides. With high coverage, baseline score of 3 is appropriate.

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

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

The description clearly states the tool's action ('Submit an initial scope of work') and the target audience ('legal vendor for negotiation'). It effectively distinguishes from sibling tools like 'swp_bid' and 'swp_counter' by specifying it's for initial proposals.

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

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

The description includes a usage guideline: 'Use when a user wants to engage a vendor for specific legal work but the spec may need vendor input to finalize.' This provides context but lacks explicit when-not-to-use or alternative tool references.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, meaning it's a modification but not destructive. The description adds that it involves 'answering' and 'submitting', but provides no further behavioral details such as whether it updates an existing spec or creates a new one, or any side effects. The minimal description does not add significant context beyond the annotations.

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

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

The description is a single sentence, making it concise. However, it is overly terse and omits important details. It earns its place but could be more structured to include parameter hints or usage context.

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

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

Given the complexity (3 required parameters with nested objects), the description is incomplete. It does not explain the input format for answers or the updated_work_spec object. There is no output schema, and the description does not indicate what the tool returns. It lacks guidance on how this tool fits in the workflow with siblings like swp_clarify.

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%, and the description does not explain the parameters beyond vague references to 'answers' and 'updated work spec'. It does not define the structure of the answers array (question_id, answer) or the session_id parameter. The description adds very little meaning beyond the schema itself.

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

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

The description clearly states that the buyer answers vendor clarifying questions and submits an updated work spec. It uses specific verbs ('answers' and 'submits') and identifies the resource ('work spec'). This distinguishes it from siblings like swp_clarify (asking questions) and swp_accept (accepting a proposal).

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 that the tool is used after receiving clarifying questions from vendors, but it does not explicitly state when to use it vs. alternatives. There is no mention of when not to use it or which sibling tools are complementary. Given the many siblings, clearer guidance would be beneficial.

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 show destructiveHint=true, so mutation is known. Description adds 'Terminal' indicating finality, but no other behavioral details (e.g., state changes, side effects). Adequately supplements 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 concise sentences with no waste. Front-loaded with the core action 'Reject the current session'. Ideal 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?

Covers purpose and caller but omits details on note parameter, return values, and exact session impact. Adequate for a simple rejection but incomplete for full autonomous 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?

Schema coverage is 0%, yet description only mentions 'reason' is a structured enum without explaining values or purpose. No details on session_id or note. Fails to compensate for 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?

Description clearly states 'Reject the current session' with a specific verb and resource. It notes 'Terminal' and 'Either party can call', distinguishing it clearly from sibling tools like swp_accept, swp_counter, 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?

Mentions 'Either party can call' but provides no explicit when-to-use or when-not-to-use guidance. Usage is implied as terminating a session, but no alternatives are mentioned.

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

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

Annotations declare readOnlyHint=true, which aligns with the description. Description adds specific return data and participant requirement, going beyond annotations.

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

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

Two concise sentences, front-loading the key purpose ('Read-only. Returns...') and adding a crucial prerequisite ('Caller must be a participant.') without any 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?

For a simple read-only tool with one parameter and no output schema, the description adequately covers what the tool does, what it returns, and who can call it. It is complete for an AI agent to decide when to invoke it among sibling tools.

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

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

Schema coverage is 0%, and description does not mention the session_id parameter. However, the parameter name is self-explanatory, and the description implies the session is identified by ID, so minimal value added.

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 returns specific session data (state, gate state, work spec, current bid) and is read-only. It differentiates from sibling mutation tools like swp_accept, swp_bid.

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 caller must be a participant, which is a key prerequisite. It implies usage for reading session status before negotiation actions, but lacks explicit when-not-to-use or alternative comparisons.

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