aribot

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

Annotations already indicate destructiveness and non-read-only behavior. The description adds important context about governance gates, approval flows, and the possibility of returning a special status instead of acting, which goes 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 two sentences, both directly relevant. The first sentence states the core action, and the second explains the governance behavior. 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 explains one possible outcome (requires_approval) but does not detail success responses, error conditions, or parameter interplay. With no output schema and nested objects, more completeness 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?

The schema covers 100% of parameters with descriptions. The tool description adds no additional parameter-level meaning, which is acceptable given the schema coverage, but it does not compensate for any potential 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 identifies the tool as applying a remediation in live mode through a governance funnel. It is specific about the action (apply remediation) but does not explicitly distinguish it from sibling tools like get_remediation, though the context implies the difference.

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 the tool routes through governance and may require approval, returning 'requires_approval' instead of acting. This provides good context for when to use it, though it does not explicitly state when not to use or mention alternatives like dry-run modes.

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 this is a write operation (readOnlyHint=false) and not destructive (destructiveHint=false). Description adds that it returns a poll pointer (asynchronous behavior). However, it does not mention rate limits, authentication requirements, or effects on previous scans.

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 covering purpose, resource, and return value. No filler, every phrase 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?

Tool has no output schema, so description should explain return value more fully. It mentions 'poll pointer' but doesn't clarify how to use it or that results are not immediate. Among many siblings, it stands out but could be more complete.

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

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

Schema coverage is 100% with one parameter. Description adds context: 'scan_id' is used to (re)run an existing scan, and the tool returns a poll pointer. This goes beyond the schema's description of the 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?

Description clearly states action ('start or re-run'), resource ('code-security scan for an existing scan/repository'), and what it returns ('poll pointer; results include...'). Distinguishes from siblings like 'compliance_scan' and 'get_traceability' by specifying it's for code security 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?

Description implies you need an existing scan ('for an existing scan/repository in your scope'), but does not explicitly state when to use vs alternatives, nor includes when-not-to-use or exclusions. Sibling tools have different purposes but no direct comparison.

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 highlights async behavior and return of a task id, which adds value beyond annotations. However, it does not disclose potential side effects (beyond the non-destructive hint), rate limits, or required permissions. Annotations already cover read-only and destructive hints.

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 that directly convey the core purpose, async behavior, and return value. Every sentence is efficient and relevant, 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 explains the return value (task id) since no output schema exists, but it lacks detail on polling or interpreting results. With 7 parameters and many siblings, the description could provide more context on distinguishing from related 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?

With 100% schema description coverage, the baseline is 3. The description repeats the enum values for scan_type but omits 'diagram' and 'account', though these are implied in the scoping context. Overall, the description adds minimal semantic value beyond the schema.

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

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

The description clearly states the tool runs a cloud/platform or compliance scan against an account or diagram, with specific scan types enumerated. It distinguishes the tool's async nature and return of a task id, making its 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 implies usage for initiating scans but does not provide explicit guidance on when not to use this tool or mention alternative tools like compliance_status or get_cloud_compliance for checking results. The context is clear but lacks 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 already declare readOnlyHint=true. Description adds that it wraps the traceability company rollup, providing aggregation context. No hidden behaviors disclosed, but no contradictions. Could mention error behavior for invalid scan_id.

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

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

Two sentences, front-loaded with key information. Every word earns its place. No fluff.

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

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

No output schema, but description lists return values (pass rate, etc.). Given the tool's simplicity and complete annotations, the description is sufficiently complete.

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

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

Schema covers 100% of parameters with descriptions. Description does not add new meaning beyond summarizing parameters as 'Optional anchor scan' and 'Optional diagram.' 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 provides a company-level compliance posture rollup including pass rate, control compliance, mitigated counts, and per-framework coverage. It distinguishes itself from siblings like compliance_scan (runs a scan) and get_framework_coverage (more specific).

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 it is 'Suitable for a CI gate,' giving a clear usage context. Does not explicitly mention when not to use or alternatives, but the context is sufficient for a simple 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?

With no annotations provided, the description carries the full burden. It indicates the tool reads from code review data (ShadowAIReport/ShadowAIDiscovery) but does not disclose side effects, authentication needs, or limitations. The tool appears read-only but this is not explicitly confirmed.

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, front-loading the main purpose and key outputs. Every sentence adds unique information 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 the tool's simplicity (2 parameters, no output schema), the description is fairly complete. It lists the contents of the response and usage modes. However, it omits details on result ordering, pagination, and the default limit behavior, which could be improved.

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

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

Schema coverage is 100%, so the baseline is 3. The description minimally adds to the schema by clarifying that scan_id selects a specific scan or defaults to company-wide latest, but it does not explain how limit affects results (e.g., pagination or ordering). The value added is marginal.

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 what the tool does: discover unsanctioned AI service usage in code. It specifies the type of data returned (totals, risk score, breakdown, hardcoded-key count, top discoveries) and distinguishes itself from sibling tools like code_review_scan or get_insights by focusing specifically on shadow AI posture.

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 retrieving shadow AI posture but does not explicitly guide when to use this tool over alternatives like get_insights or compliance_scan. It mentions that scan_id is optional but lacks guidance on prerequisites or frequency of 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?

The description adds context beyond annotations: it mentions auto-generation of threats, ingestion via shared service, and return of diagram id. Annotations indicate mutation (readOnlyHint=false) and non-destructiveness, which align with creation. 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?

Three sentences, each essential: purpose, ingestion method, and return value. No redundant words. Front-loaded with the core action.

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 purpose, input, pipeline, and output. Lacks details on error scenarios or prerequisites, but annotations and schema provide some context. Adequate for a creation tool with moderate 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?

With 100% schema coverage, the schema already documents all parameters. The description adds minimal parameter-specific context (e.g., 'normalized architecture' and 'Stage-0 service'), but this is system-level rather than detailed semantics. 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 'Create', the resource 'threat model', and the input 'ReactFlow nodes + edges'. It uniquely identifies this tool among siblings, which focus on other tasks like remediation or 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 implies usage for generating threat models from architecture data but does not explicitly state when to use or when not to use, nor does it mention alternatives. Sibling tools are distinct enough to avoid confusion, but guidance is only implicit.

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 correctly indicates a read-only operation by stating 'reads code_review ApiEndpointDiscovery' and describing retrieval of inventory. It does not mention any side effects or authorization requirements, but the read intent is clear.

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

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

The description is three sentences, front-loaded with the main purpose, and contains no extraneous information. Every sentence earns its place 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?

Despite no output schema, the description details what is returned (endpoints with auth status, risk levels, breakdowns) and the data source. It is sufficiently complete for an agent to understand the tool's output and context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that omitting scan_id retrieves company-wide data, which goes beyond the schema description. The limit parameter is not elaborated, but the overall context is helpful.

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 an API security inventory with discovered endpoints, authentication status, risk levels, and breakdowns. It specifies the scope (company-wide or per scan) and differentiates from sibling tools like get_cloud_compliance or code_review_scan.

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 API security within Code Security and notes when to use scan_id for a specific scan vs company-wide. However, it does not explicitly state when not to use this tool or compare to alternatives like compliance scans.

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

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

With no annotations, the description carries full burden. It discloses that request_plan 'files a request for super-admin approval — never grants', which is a key behavioral constraint. It also indicates that passing topup_amount or checkout_request_id returns hosted Checkout URLs. No destructive behavior is hidden; mutation is expected for payment actions.

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-loading the main purpose. It efficiently covers the tool's capabilities and parameter behaviors without unnecessary repetition. Slightly long first sentence but overall 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 that the tool has multiple modes (view, request, top-up, complete) and no output schema, the description provides a good overview of return content (status fields, checkout URLs). It could be more explicit about response structure or error handling, but it covers essential information 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 100% with descriptions for each parameter. The description adds context by explaining the overall effect of parameters (e.g., returning hosted checkout URLs) and clarifying that request_plan does not grant or charge. This goes beyond the schema's minimal 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 purpose: 'Billing status + self-service payment' and lists specific items (credit-wallet balance, pay-per-use flag, license tier, etc.). The verb ('get' in name, 'view' in description) and resource are well-defined, and there are no sibling billing tools to confuse.

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: 'Use this to view or RESOLVE a 402 without leaving the connector.' It also provides context for each parameter (checkout_request_id, topup_amount, request_plan) and their effects. It does not explicitly state when not to use it, but the use cases are clear enough for an agent.

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

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

With no annotations, the description carries full burden. It indicates a read operation ('Reads ...') and describes the data source. It lists output elements (compliance %, failing policies/records, status, rollup), providing decent transparency, though it lacks mention of side effects, permissions, or caching behavior.

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 purpose, and avoids fluff. It is concise and structured, though slightly longer than the ideal one-sentence summary.

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 (1 optional param, no output schema, no annotations), the description provides sufficient context: purpose, input parameter, output elements, and data source. It could be more complete by explicitly stating it is read-only, but overall it is adequate.

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

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

Schema coverage is 100% with a clear description of the single optional parameter. The description does not add additional parameter context beyond the schema, but baseline 3 is appropriate as the schema already documents it well.

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 cloud compliance posture, specifying CIS/NIST scans, per account and company rollup. It is specific about the resource and output, but does not explicitly distinguish from sibling compliance tools like compliance_scan 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 through its topic (cloud security compliance posture), but offers no explicit guidance on when to use this tool versus alternatives like compliance_scan or get_framework_coverage, nor does it mention when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context by specifying the summary content (threat counts by severity, risk value, compliance, framework coverage), which goes 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 sentence that front-loads the purpose and content. Every word adds value with no redundancy or unnecessary details.

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, the description is complete. It explains what the summary contains, compensating for the lack of an output schema. However, it could mention if the response is paginated or limited to certain data.

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 a single parameter diagram_id described in the schema. The description does not add additional meaning beyond what the schema already 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 canonical diagram summary with specific components (threat counts, risk value, compliance, framework coverage), distinguishing it from sibling tools like get_framework_coverage or get_insights which are more specific.

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 badges/cards/headers (quick display), but does not explicitly mention when not to use or provide guidance on selecting between siblings. Usage is implied, not explicit.

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 openWorldHint=false. The description adds value by revealing that the tool wraps two internal functions (derive_framework_coverage and crossmap_cypher.build_graph), implying it is computationally heavier than a simple query. 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 two sentences, front-loaded with the core purpose, and no wasted words. Every sentence adds value, including the implementation detail which aids transparency. Highly concise while informative.

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

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

Given three parameters and no output schema, the description explains the return includes coverage and optionally a graph. However, it does not describe the structure of coverage or the graph format. Adequate for a simple getter but leaves some gaps for an agent needing to parse results.

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 all three parameters. The description rephrases the optional parameters but does not add new semantic information beyond that. Baseline 3 is appropriate as the description does not compensate for any missing schema 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 states 'Compliance-framework coverage for a diagram' with specifics about being 'real, ControlCodeMap-backed' and optional graph. This clearly identifies the tool's purpose and resource. However, it does not explicitly distinguish from sibling tools like compliance_status or compliance_scan, which could have overlapping functionality.

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 getting coverage with optional crossmap graph, but it does not provide guidance on when to choose this tool over siblings. There is no mention of prerequisites, when not to use, or explicit context such as filtering by framework. The agent lacks clear decision criteria.

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, openWorldHint, and destructiveHint, so the safety profile is covered. The description adds behavioral context by noting the join with a code-security scan conditionally, which is valuable 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 a single, well-crafted sentence that front-loads the core purpose and includes key behavioral details without any wasted words. It is optimally 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 no output schema, the description adequately explains what the tool returns: metrics, coverage, and optionally scan data. However, it could be more explicit about the structure or format of the metrics and coverage information.

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 diagram_id described as 'Diagram id/uuid'. The description does not add any extra meaning or usage detail for this parameter beyond what the schema provides, so it scores baseline.

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/control matrix metrics + framework coverage for a diagram, joined with its latest code-security scan when one exists.' This specifies a clear verb (get), resource (insights), and scope (diagram, with optional scan data), distinguishing it from siblings like get_diagram_summary or 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 when needing a combined view of metrics, coverage, and optional scan data, but does not explicitly state when to use this tool versus alternatives such as get_framework_coverage or apply_remediation. No exclusions or when-not-to-use 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?

Beyond annotations (readOnlyHint, openWorldHint), the description adds key behavioral traits: it does NOT apply the plan, runs the same engine as apply_remediation, includes patent gates, and returns proposed steps. This adds significant value 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?

Two sentences, no wasted words. The purpose is front-loaded, and each sentence adds 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 the three parameters (one nested) and no output schema, the description explains what the tool does and returns, but does not specify the output format or structure of the proposed steps. It is adequate but could be more complete.

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

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

Schema coverage is 100%, so the schema already documents all three parameters with descriptions. The description does not add further meaning beyond the schema, so a baseline 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 it computes a remediation plan without applying it, using a dry run mode. The verb 'compute' and resource 'remediation plan' are specific, and it explicitly distinguishes from the sibling 'apply_remediation'.

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 (to get guidance without applying) and implies the alternative 'apply_remediation'. It mentions running the same engine including patent gates, providing useful context. However, it does not explicitly state when not to use or list other 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 provide readOnlyHint=true, already indicating no side effects. The description adds value by disclosing the returned data structure (diagram→threat→finding→control→requirement→remediation chain and coverage metrics), which is beyond the annotations. No contradictions, and the description complements the read-only nature.

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, clear sentence that immediately states the action and output. Every word is purposeful: 'Return' (action), 'diagram→threat→finding→control→requirement→remediation traceability matrix' (output), 'for a scan in your scope' (scope), 'with coverage metrics' (additional output). 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 no output schema, the description fully describes the return value (the traceability chain and coverage metrics). The tool has only one required parameter, and the description conveys the output's richness. For a simple retrieval tool, this is complete and sufficient for an agent to understand what the tool provides.

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

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

The input schema has 100% coverage with a single required parameter (scan_id) described as 'Code-review scan id'. The description adds context by scoping it to 'a scan in your scope', which clarifies access permissions and eligibility, meaningfully 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 returns a traceability matrix for a scan, specifying the exact chain (diagram→threat→finding→control→requirement→remediation) and includes coverage metrics. The verb 'return' and resource 'traceability matrix' are specific. Among siblings like get_compliance_status or generate_threat_model, this tool is uniquely for traceability, providing clear differentiation.

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 retrieving traceability of a scan in scope but does not provide explicit when-to-use or when-not-to-use guidelines. No alternatives or exclusions are mentioned. The sibling list includes many related tools (e.g., get_diagram_summary, verify_threats_in_code), but the description offers no comparative guidance, leaving the agent to infer appropriate context.

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

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

With no annotations, the description covers idempotence, license/grant requirements, and self-onboarding behavior, but omits details on error handling or rate limits.

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

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

The description is information-dense and front-loaded, though the first sentence is long; it efficiently conveys all key aspects 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 does not specify return values or error outcomes, which are relevant for an agent understanding the full effect of the 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 descriptions cover all 4 parameters at 100%; the description adds context about A2A cards, MCP descriptors, and auto-suspend policy, exceeding baseline.

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 'bulk-onboard' and the resource 'agent identities to the governed fleet', which is distinct from sibling tools focused on scanning, compliance, and remediation.

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 the tool is for bulk onboarding and mentions self-onboarding as an alternative, but does not explicitly state when to avoid using the tool or compare directly 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 mark it as readOnly and openWorld, but the description adds important behavioral details: synchronous vs async execution, background processing for all threats, and service wrapping. 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 extremely concise: two sentences with no wasted words. Key information (purpose, modes, service reference) is front-loaded, making it efficient for an AI agent 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?

For a tool with 5 parameters and no output schema, the description is reasonably complete (modes, synchronous vs async). However, it does not describe return values or error behavior, which could be useful given the 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 80%, but parameters like async_, code_content, and repository_id lack descriptions in both schema and the tool description. The description does clarify the role of threat_id, but overall parameter meaning is not fully enriched.

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: verifying threat mitigation in code. It distinguishes two modes (with/without threat_id) and references the underlying service, making the action specific and differentiable from sibling tools like code_review_scan or get_remediation.

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 each mode (synchronous vs background verification), offering clear context. However, it does not state when to avoid this tool or suggest alternatives, slightly limiting completeness.

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