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?

readOnlyHint=true and openWorldHint=false already declare the safe-read, closed-world profile, so the description's main added value is the company-wide, all-framework scope. It adds no detail on aggregation behavior, freshness, or what the rollup contains, leaving the behavioral picture thin beyond what the 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?

A single front-loaded sentence that packs scope, frameworks, and intended use with zero filler. Nothing redundant and nothing to trim.

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, zero-required-parameter aggregation tool with no output schema, the description conveys what the result represents (company-level posture across all frameworks) and who consumes it. Only minor gaps remain, such as how the optional scan_id/diagram_id filters change the rollup.

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 scan_id and diagram_id are already documented in the schema. The description never references either filter, adding no semantics beyond the baseline for fully covered 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?

States a specific verb (rollup) and resource (company-level compliance posture) and enumerates the frameworks covered, which distinguishes it from the per-framework tools like get_framework_coverage and get_cloud_compliance. It stops short of naming a sibling or explicitly contrasting itself with compliance_scan, which likely initiates the scan this tool summarizes.

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?

It hints at context via "suitable for CI gates and executive reporting," which implies read-only aggregation use, but it never states when to prefer this over compliance_scan, get_framework_coverage, or get_cloud_compliance. Usage must be inferred rather than read.

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=false, openWorldHint=true, and destructiveHint=false, so the agent knows this is a non-destructive but stateful, externally-reaching operation. The description adds the '(async)' flag, which is valuable since it implies the call returns before completion and results must be fetched later. However, it omits how/when results become available, expected duration, and any auth or connectivity requirements for the network-traffic scan.

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?

A single front-loaded sentence with a dense but relevant enumeration of scan targets, and no filler. The trailing '(async)' is the only slightly under-explained element, but overall it is 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?

For an async discovery scan with no output schema, the description should ideally say how to obtain results and roughly what to expect. It flags async execution but leaves the agent without a retrieval path or expectations for a potentially long-running network scan, so it is only partially complete.

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

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

With a single parameter at 100% schema description coverage, the schema already explains that scan_id identifies the uploaded code or repository. The description's phrase 'connected repositories' adds only marginal context, implying the scan_id must reference an already-onboarded target. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

States a specific verb (scan) and precise resources (connected repositories, network traffic) plus the exact targets (unmanaged LLMs, model endpoints, vector DBs, agent frameworks, leaked API keys). This makes it clearly distinguishable from siblings like code_review_scan or compliance_scan. It does not explicitly name a sibling to contrast against, so it falls short of a 5.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives among the many scan-type siblings (code_review_scan, compliance_scan, generate_threat_model). The '(async)' note hints at invocation behavior but gives no routing guidance. An agent must infer that this is the tool for shadow-AI discovery purely from the resource list.

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

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

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, so the safety profile is covered. The description adds that results are 'real ControlCodeMap-backed' and enumerates the output categories, which is useful, but it says nothing about scoping behavior, cost, or what happens when a framework is unsupported.

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?

A single front-loaded sentence with no filler; the verb and payload come first. The trailing 'etc.' and the long framework list are slightly loose but not wasteful.

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 usefully names what is returned (coverage percentages, gap counts, mapped controls), covering the main gap. It leaves the include_graph graph behavior and failure modes unexplained, which is the only notable omission for a 3-parameter read 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 framework, diagram_id, and include_graph are all documented in the schema itself. The description's framework list (EU AI Act, DORA, NIST, ISO 27001, SOC 2) loosely illustrates the framework filter but adds no syntax or format detail beyond the schema's own examples, so 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?

States a specific verb (Get) and resource (framework coverage) and enumerates the concrete return values: coverage percentages, gap counts, and mapped controls. It does not, however, explicitly distinguish itself from near siblings like get_cloud_compliance or compliance_status, leaving the agent to infer the boundary.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as compliance_status or get_cloud_compliance. The 'real ControlCodeMap-backed' qualifier hints at authority but does not tell the agent when this tool is the correct choice.

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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavior context by disclosing the synchronous-vs-batch dispatch modes, but says nothing about how the batch path reports back, latency, or any limits.

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

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

Two tightly packed sentences with zero filler. The core purpose is front-loaded and the mode-switching rule follows immediately, so an agent can read the whole contract at a glance.

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?

Read-only annotations and a fully documented schema cover most of the contract, but with no output schema the description should explain what each mode returns. The batch path is described only as 'dispatches,' leaving the agent unsure whether it gets results, a job handle, or nothing back.

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, but the description adds real meaning: presence of threat_id switches the tool from batch to synchronous single-threat verification. It also clarifies that verification runs against uploaded code or AST, tying to code_content, though scan_id and repository_id get no added explanation.

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?

States a specific verb (verify) and resource (STRIDE/LINDDUN threats in a scan's uploaded code or AST), which clearly separates it from generate_threat_model and code_review_scan. However, it never names a sibling or explicitly contrasts itself with the threat-modeling and remediation tools, so the differentiation is implicit.

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 second sentence gives an explicit decision rule: supplying threat_id yields a synchronous verdict, omitting it dispatches batch verification across diagram threats. That is a genuine when-to-use branch, but there is no guidance on prerequisites, when not to use it, or which sibling to pick for related tasks.

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