aribot

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

Builds on annotations (destructiveHint=true) by describing governance funnel and potential conditional behavior (approval), adding context beyond structured fields.

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

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

Two concise sentences pack purpose and key behavioral nuance 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?

Lacks full return value specification (only describes approval case) and leaves terms like 'patent reachability/kill-chain gates' unexplained, though schema details parameters 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 coverage is 100% so baseline is 3; description does not add meaning beyond schema for any parameter.

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

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

Clearly states 'Apply a remediation for real (mode=live)' and distinguishes from sibling 'get_remediation' by emphasizing live action through governance funnel.

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 specific behavioral context ('If your policy requires approval it returns requires_approval') but lacks explicit when-not-to-use or alternatives beyond approval mention.

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 non-read-only and non-destructive. Description adds return pointer and result types but does not disclose side effects like overwriting results or potential failures.

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. Action and return info 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?

Given single parameter and no output schema, description covers return types but omits error cases, prerequisites, or limitations. Adequate for 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?

Parameter schema provides description already. Description adds context 'existing scan/repository' but does not significantly augment meaning beyond schema.

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

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

Description uses specific verb 'Start (or re-run)' and targets specific resource 'code-security scan for an existing scan/repository', clearly distinguishing from siblings like compliance_scan or get_traceability.

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?

Indicates use case (for existing scan/repository) but lacks explicit when-not-to-use or alternatives. Implied usage from context but no direct guidance.

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

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

Annotations already indicate non-readonly, non-destructive, and open world. Description adds async execution and task id return, but does not disclose potential side effects (e.g., cost, rate limits) beyond the simulation_mode parameter.

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 very concise—two short sentences. It front-loads the core purpose and includes only essential details without any filler.

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

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

Given the async nature and 7 parameters (mostly described in schema), the description covers the key behavioral aspects (initiation, task id, enum constraints). It lacks details on return format and lifecycle, but no output schema exists. Overall, it is fairly complete for its 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 description coverage is 100%, so baseline is 3. The description restates some enum values but adds no extra meaning for parameters like source, frameworks, or severity_filter. The schema already provides adequate documentation.

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

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

The description clearly states the action ('Run a cloud/platform or compliance scan'), the resources ('account or diagram'), and the async nature. It distinguishes from sibling tools like compliance_status by implying initiation vs status 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 does not explicitly state when to use this tool vs alternatives like compliance_status or get_cloud_compliance. It implies that this is for starting scans, but lacks guidance on prerequisites or post-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?

Annotations already declare readOnlyHint=true (safe read). The description adds behavioral context: it is a rollup (aggregated), suitable for CI (implies speed/caching), and wraps the traceability company rollup. This adds 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 three targeted sentences. Every sentence adds unique value: rollup content, CI suitability, and underlying source. No redundancy.

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

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

Given two optional parameters, no output schema, and annotations present, the description covers the output nature, usage context, and source. It does not detail return format but is adequate for the tool's 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% with clear parameter descriptions. The description further clarifies the purpose of diagram_id (adding per-framework coverage) and scan_id (anchor or latest), complementing 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 provides a company-level compliance posture rollup with specific metrics (pass rate, control compliance, mitigated counts, per-framework coverage), distinguishing it from sibling tools that are more granular or focus on other aspects.

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 suitability for a CI gate, providing clear usage context. It does not explicitly exclude other scenarios or directly compare with siblings like compliance_scan, but the context is sufficient for informed 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?

With no annotations, the description takes full burden. It discloses that the tool reads code_review ShadowAIReport/ShadowAIDiscovery and lists the returned fields, revealing its read-only nature. No contradictions are present.

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, information-dense sentence that efficiently communicates purpose, output, and usage. It could be slightly restructured for readability, but it is concise 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?

Given no output schema, the description adequately describes the return fields (totals, risk score, breakdown, etc.) and the data source. It covers the essential information for a list 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%, and the description adds minor clarification about scan_id omission giving company-wide latest, but the schema already explains this. The description does not provide additional semantics 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 tool discovers unsanctioned AI service usage in code, providing specific outputs like totals, risk score, breakdown, and top discoveries. It is distinct from sibling tools like compliance_scan or get_api_security, which focus on other security areas.

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

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

The description explains that it fetches company-wide latest data or data for a specific scan_id, giving clear usage context. However, it does not explicitly state when not to use this tool or provide alternatives among 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?

Discloses internal pipeline and service dependency but does not elaborate on side effects, permissions, or potential issues. Annotations don't contradict description.

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, well-structured, front-loaded with key information. 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 inputs, process, and output. Could mention if async/blocking or ordering relative to sibling tools like verify_threats_in_code.

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%; description does not add parameter-specific details beyond what 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?

Clearly states verb (create), resource (threat model), inputs (ReactFlow nodes+edges), process (via Stage-0 service, auto-generates threats), and output (diagram id). Distinct from sibling tools like get_diagram_summary.

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

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

Implied usage (creating from architecture) but no explicit guidance on when to use vs alternatives, no exclusions or prerequisites 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?

With no annotations provided, the description carries the full burden. It states the tool reads data from code_review ApiEndpointDiscovery, implying a read-only operation. It describes the output (auth status, risk level, etc.) but does not explicitly state destructive behavior or permissions. No contradictions with annotations.

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

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

The description is a single sentence that efficiently conveys the tool's purpose, scope, and behavior. Every piece of information is relevant, and there is no redundancy. It is well-structured and front-loaded with the key concept.

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 the return fields (auth status, risk level, risk factors, method/risk breakdowns). It also covers input scoping. The description is mostly complete, though it could elaborate on the method/risk breakdowns slightly more.

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 both parameters (limit, scan_id) with descriptions. The description adds context that scan_id is optional and company-wide if omitted, but this is already implied by the schema's description. The description does not significantly enhance understanding beyond what the schema provides, scoring baseline 3.

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

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

The description clearly states the tool retrieves an API security inventory with authentication status, risk level, and breakdowns. It identifies itself as part of Code Security and specifies that it reads from code_review ApiEndpointDiscovery, distinguishing it from sibling tools like compliance_scan or get_cloud_compliance.

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 the tool can be used company-wide or for a specific scan via scan_id, providing clear context for when to use it. However, it does not explicitly mention when not to use it or compare it with alternatives among the 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?

No annotations provided; description discloses key behaviors: request_plan 'files a request for super-admin approval — never grants,' and that parameters return hosted Checkout URLs. Lacks mention of auth or rate limits but overall thorough.

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?

Packed with useful information in a single paragraph; front-loaded with purpose. Could be slightly more structured but 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 behaviors and parameter usage. No output schema, so description does not detail return format, but the intended use is clear. Adequate for a billing status 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 descriptions, but the description adds operational context (e.g., checkout_request_id for 'approved plan', topup_amount for 'top up', request_plan for 'request'). Adds value beyond 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 explicitly states 'Billing status + self-service payment' and lists specific capabilities (credit-wallet, pay-per-use, license tier, etc.), distinguishing it from sibling tools focused on security/compliance.

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?

Clearly states when to use ('view or RESOLVE a 402'), explains each parameter's function, but does not explicitly mention 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?

With no annotations, the description only indicates it is a read operation ('Reads'). It does not disclose authentication requirements, rate limits, potential data staleness, or whether it triggers any side effects. Minimal behavioral context beyond data source.

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

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

The description is two concise sentences that front-load the tool's purpose and quickly describe the output and data source. 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?

Given no output schema, the description provides a reasonable summary of return values (compliance %, failing policies/records, status, rollup). However, it could more explicitly describe the structure of the rollup and any pagination or ordering. Account_id parameter is well-covered.

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 adds value by explaining that omitting account_id returns data for all company accounts, and that results per account include compliance percent and failing policies. This clarifies the optional parameter's behavior 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 that the tool retrieves cloud compliance posture per account and provides a company rollup, including specific metrics like compliance percentage and failing policies. It uses specific verbs ('get' implied) and distinguishes from sibling tools like 'compliance_scan' which likely initiates scans.

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 viewing aggregated compliance posture per account, but does not explicitly state when to use this tool over siblings like 'compliance_scan', 'compliance_status', or 'get_framework_coverage'. No exclusion criteria or prerequisites are mentioned.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, which the description does not contradict. The description adds value by listing the specific return components (threat counts, risk value, compliance, framework coverage), which helps the agent understand the output 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, well-structured sentence that front-loads the key point ('canonical diagram summary') and lists the contents. No unnecessary words or repetition.

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 content of the summary adequately but lacks details on output format, error conditions, or prerequisites (e.g., diagram must exist). For a simple read tool with no output schema, and given the sibling tools' complexity, more completeness (e.g., structure of the summary, error handling) would be beneficial.

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

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

With only one parameter (diagram_id) and 100% schema description coverage (description: 'Diagram id/uuid'), the description adds no additional meaning. The baseline for high schema coverage is 3, and there is no extra semantic value in the description.

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 'threat counts by severity, risk value, compliance and framework coverage', which is a specific and distinct purpose. It also positions it as the 'canonical diagram summary' for badges/cards/headers, differentiating it from sibling tools like get_framework_coverage or compliance_status.

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 via 'canonical...every badge/card/header reads', but does not provide explicit when-to-use or when-not-to-use guidance, nor does it reference alternatives among the 15 sibling tools. This leaves the agent to infer context without clear boundaries.

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, indicating a safe read operation. The description adds that it wraps two functions (derive_framework_coverage + crossmap_cypher.build_graph), implying some computation, but lacks details on performance or data freshness. This is adequate but not rich.

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

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

The description is two sentences, front-loaded with the main purpose, and every sentence adds value. It is concise and well-structured.

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

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

With no output schema, the description should clarify what the tool returns (e.g., a list of controls, statuses, or a graph). It only mentions 'Compliance-framework coverage' and 'crossmap relationship graph', which is vague. The return format is unspecified, leaving the agent uncertain about the result 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 baseline is 3. The description paraphrases the schema (e.g., 'optionally for one framework' matches framework parameter) without adding meaningful new details. No extra semantics are provided 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 tool retrieves compliance-framework coverage for a diagram, optionally filtered by framework and with a crossmap graph. It uses specific terms like 'ControlCodeMap-backed' and references internal functions, but it is understandable for those familiar with the domain.

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

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

The description provides no guidance on when to use this tool versus siblings like compliance_status or compliance_scan. It does not mention prerequisites, limitations, or when to use optional parameters.

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 read-only, non-destructive behavior. The description adds behavioral context by stating the conditional join with the latest code-security scan if one exists, which is beyond what annotations provide.

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

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

The description is a single, well-structured sentence that front-loads the key output and conditions, with 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 the single required parameter and no output schema, the description sufficiently explains what the tool returns. It covers the core functionality without gaps, though it could mention if there are any prerequisites for the join to occur.

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 'diagram_id'. The description does not add additional semantic information beyond the schema's description of 'Diagram id/uuid'.

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

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

The description clearly identifies the tool as returning threat/control matrix metrics and framework coverage for a diagram, optionally joined with a code-security scan. This distinguishes it from siblings like get_diagram_summary and get_framework_coverage.

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 obtaining combined insights but does not explicitly state when to use this tool versus alternatives like get_diagram_summary or code_review_scan. No when-not or alternative guidance 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 declare readOnlyHint=true, so the description adds value by explaining it does not apply the plan, runs the same governed engine, includes patent gates, and returns steps. No contradictions. Could mention output specifics.

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. First sentence states core purpose and mode. Second sentence adds engine context and output type. Concise 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?

While the purpose is clear, the description lacks detail on the output format of the remediation plan (no output schema). It mentions 'returns the proposed steps' but does not describe structure. Also, 'patent gates' is unexplained. More output detail would improve 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% with all parameters described. The description adds no new parameter-level information beyond what's in 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 clearly states the verb 'Compute' and the resource 'remediation plan for a threat/finding'. It explicitly distinguishes itself from the sibling 'apply_remediation' by noting 'WITHOUT applying it (mode=dry_run)' and references the same governed engine, ensuring no confusion.

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 this tool (for a dry-run preview) and names the alternative 'apply_remediation' for actual application. It provides context by noting it runs the same engine, but lacks explicit 'when not to use' guidance.

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

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

Annotations already label the tool as read-only (readOnlyHint=true). The description adds that it returns a matrix with coverage metrics, providing context about the data structure. No contradictions. It adds some value beyond annotations but does not disclose potential performance or access constraints.

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, information-dense sentence. No wasted words. It is 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?

The tool has no output schema, so the description hints at the return value (traceability matrix with coverage metrics). This is sufficient for a simple, read-only, single-parameter tool. However, it does not detail the matrix structure or potential pagination.

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

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

The schema covers the only parameter (scan_id) with a description ('Code-review scan id'). The description does not add additional meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns a traceability matrix for a scan, with coverage metrics. It uses a specific verb ('Return') and resource ('traceability matrix'). Among sibling tools, no other tool appears to provide this specific matrix, so it is well-distinguished.

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 the tool is for a scan in the user's scope, implying a usage condition. However, it does not explicitly state when not to use it or suggest alternatives. The guidance is clear but could be expanded with 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 provide readOnlyHint and openWorldHint. The description adds meaningful behavioral details: synchronous vs. background execution, and that it wraps a service. No contradictions; it enriches the annotation-provided context.

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

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

Two sentences, no wasted words. First sentence declares purpose, second explains behavioral modes. Efficient and well-structured.

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

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

With no output schema, the description should better explain return values; it only hints 'returns the verdict' for synchronous mode. Background mode's result retrieval is unaddressed. Potential parameter conflicts (threat_id + async_) are not covered.

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 high (80%), so baseline is 3. The description adds value by explaining that threat_id changes the mode, but does not clarify the async_ parameter's role or interaction with threat_id. Some parameter semantics remain unclear.

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

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

The description states the specific verb 'Verify' and resource 'threats in code', clearly distinguishing two modes: synchronous with threat_id and background without. This differentiates it from siblings like apply_remediation, which is about applying fixes.

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

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

The description explains when to use the tool (to verify threats) and outlines two behavioral modes, but does not explicitly state when not to use it or mention alternative siblings like apply_remediation. The context is clear but lacks explicit exclusions.

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