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 only declare readOnly=false, destructive=false, openWorld=true. The description adds real behavioral context beyond that: the mutation also propagates to the linked ticket, and it enumerates the failure taxonomy plus idempotency/resend semantics for three terminal states. The error list is unstructured, but the recovery rules around filed_unrecorded and outcome_unknown are exactly the kind of safety detail annotations cannot carry.

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 core behavior is front-loaded in one clean sentence. However, the remaining text is an 18-item comma-separated error-code dump with no grouping, severity, or per-code meaning, which pads the definition without letting the agent act differently on most codes.

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 non-destructive mutation with no output schema, the description does cover the key side effect and failure recovery, which is the highest-value content. It still leaves gaps an agent needs: which permission/role is required (permission_missing and role_missing are listed but unexplained), and what assigning a null assignee_member_id does.

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 only 33%: due_date documents 'YYYY-MM-DD' but threat_entry_id and assignee_member_id are bare. The description says 'owner and due date' but never explains what assignee_member_id accepts, nor what a null assignee means (unassign? leave unchanged?). With low coverage, the description was expected to compensate and does not.

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

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

States a specific verb and resource ("Set the owner and due date of a threat entry") and adds the non-obvious side effect that the linked ticket follows. It is distinguishable from read-only siblings like get_threat_tickets, though it doesn't explicitly contrast with file_threat_tickets or sync_threat_tickets, which sound closely related.

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 retry guidance (don't resend filed_unrecorded/outcome_unknown without checking the tracker; resend not_attempted) is genuinely useful operational direction, but it only covers post-failure usage. There is no explicit when-to-use-this-vs-siblings guidance, particularly against file_threat_tickets and sync_threat_tickets which appear to touch the same ticket lifecycle.

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?

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, but the description adds substantial behavior beyond them: per-threat comment granularity, idempotent re-run semantics, skip reasons, a full error-code vocabulary, and retry guidance for filed_unrecorded/outcome_unknown/not_attempted. This is exactly the mutation-safety context an agent needs.

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?

Purpose and behavior are front-loaded before the error-code and retry guidance. The long enumerated error list is dense but genuinely informative; slightly heavy, yet each sentence carries usable 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?

With no output schema, the description correctly explains the return values (each comment's status: posted, updated, skipped with reason, failed) and covers skip behavior and error handling. Complete for a single-parameter 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?

With one required parameter and 100% schema description coverage, the schema already documents scan_id fully. The description frames the scan context ('completed pipeline scan of a pull request') but adds no syntax or format detail beyond the schema, so the 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 precise verb+resource: it posts/updates one comment per threat whose linked code the PR changes, scoped to a completed pipeline scan of a pull request. This is specific enough to distinguish it from siblings like file_threat_tickets or get_threat_tickets without inspecting schemas.

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

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

Gives clear when-to-use context (a completed pipeline scan of a PR), when-nothing-happens (re-run with nothing changed makes no calls), and skip conditions (public repos skipped). It stops short of explicitly naming which sibling to use instead of this one, so it is strong but not fully routing.

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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), the description discloses idempotency behavior ('a repeat returns already_filed'), a preview/side-effect-free mode, a real data-exposure warning that public_repository=true makes tickets visible to anyone, and a full error taxonomy with retry semantics for ambiguous outcomes. This is exactly the behavioral context an agent needs before triggering an external write.

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 core action, routing rule, and batch limit are front-loaded in the first sentence, and the dry_run/public_repository warnings follow immediately. The 18-item error-code enumeration is bulky, but it is material rather than filler, since it underpins the retry guidance that follows.

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 carries the return-value burden and does so for the notable paths (already_filed repeat, dry_run ticket payload) plus error outcomes. It omits what a successful filed response contains and any permission/role prerequisites, though the permission_missing/role_missing error codes partially signal those.

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 only 33% (only `destination` is documented in-schema), so the description has to compensate, and it largely does: it defines dry_run's semantics ('returns the exact tickets without sending'), the 1-50 cardinality of threat_entry_ids, and `destination` as a route override. It stops short of clarifying the nested destination fields (provider, channel_ref, destination) or the id type/format expected in threat_entry_ids.

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 names a specific verb and resource ('Send 1-50 threat report entries to the tracker') plus the routing mechanism (route or `destination`), so the agent knows exactly what action is performed and against what. It does not, however, explicitly distinguish this filing tool from siblings like sync_threat_tickets or comment_threat_on_change, which an agent evaluating near-duplicate sending tools would want.

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 gives concrete operational guidance: batch range 1-50, use dry_run=true to preview without sending, one ticket per threat per report, and specific resend rules for ambiguous outcomes (do not resend filed_unrecorded/outcome_unknown; resend not_attempted). What is missing is any explicit statement of when to use this rather than sync_threat_tickets, or prerequisite permissions before invoking.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, so safety profile is largely covered. The description adds real value by enumerating the artifacts auto-synthesized (STRIDE/LINDDUN, requirements, control mappings), but says nothing about side effects such as whether the architecture is persisted by default (only the schema's save_as_diagram notes this) or whether generation is deterministic/expensive.

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 dense sentence that front-loads the primary output (architecture) before the secondary synthesized artifacts. No filler, though it is long enough that splitting the 'what you get' from 'what you give' would read faster.

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 6-parameter generation tool with no output schema, the description adequately covers what is produced and from what input. It omits return shape and persistence behavior, which is acceptable given the rich schema, but those gaps keep it short of full completeness.

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

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

Schema description coverage is 100% and every parameter has its own description, including enum values and an example for compliance_standards, so the schema carries the load. The description adds no format or syntax detail beyond the schema, which is the baseline 3 case.

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 (generate) and concrete resources (multi-tier cloud/AI architecture plus STRIDE/LINDDUN threat models, security requirements, compliance mappings) from a natural-language prompt. It is clear on its own, but it never distinguishes itself from the sibling generate_threat_model, so an agent cannot tell which one to pick when a threat model is the goal.

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 or when-not-to-use guidance. The description implies this is the broad 'design from a prompt' entry point, but with siblings generate_threat_model and compliance_scan doing overlapping work, the agent is left to infer the routing condition itself.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful context beyond that: the data derives from 'code_review ApiEndpointDiscovery' and that omission of scan_id yields the whole company — a behavioral scoping fact not present in the annotations.

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

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

Two compact sentences/fragments that are front-loaded with the resource and its contents before the scoping note. No filler, though the trailing 'Reads code_review ApiEndpointDiscovery' is somewhat terse and slightly under-explained.

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 carries the burden of describing returns, and it does — endpoints, auth status, risk level, factors, and breakdowns. Combined with annotation-covered safety and a fully documented two-param schema, an agent has nearly everything needed to call it correctly; only explicit sibling routing is absent.

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 both limit and scan_id are already documented in the schema. The description only restates the scan_id omission behavior ('company-wide if omitted'), adding no new semantic detail beyond the structured field. 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?

States a concrete verb+resource (API security inventory of discovered endpoints) and enumerates the payload: authentication status, risk level, risk factors, and method/risk breakdowns. That level of specificity lets an agent distinguish it from generic sibling tools like get_insights 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 explains the scoping choice — 'Company-wide or one scan with scan_id' — which is real usage guidance for the parameter. However, it never names an alternative tool or states when this inventory is preferable to a related sibling (e.g., compliance_scan, get_cloud_compliance), so usage is only implied.

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 (readOnlyHint=false, openWorldHint=true) establish the mutating/open-world profile, and the description adds real value on top: it clarifies that request_plan 'files a request for super-admin approval — never grants,' which prevents the agent from assuming access is provisioned. It also discloses that topup/checkout calls return hosted Stripe Checkout URLs, i.e. an external redirect consistent with openWorldHint. It stops short of stating auth/permission requirements or idempotency, so a 4 rather than 5.

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 dense sentences, front-loaded with the resource and return contents before the parameter-driven modes; capitalized verbs (RESOLVE, COMPLETE, TOP UP, REQUEST) aid scanning. There is mild redundancy between the parameter descriptions in the schema and the description text, but nothing is wasted enough to impair readability.

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 carries the return-value burden and does so by listing the status fields returned and noting that certain parameters yield a hosted Checkout URL. The behavior of all three optional parameters is covered, and nothing an agent needs to invoke it correctly is missing. It could be more complete on the shape of the returned plan/price data, but for a zero-required-parameter tool this is solid.

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 each parameter's meaning, and the description does not repeat this gratuitously. It does add value beyond the schema by enumerating the valid plan keys (starter|pay_per_use|pro|max|enterprise), which the schema lacks as an enum, and ties each parameter to its resulting action. Baseline 3 is exceeded by that added semantic detail.

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 names a specific resource (company billing/plans) and enumerates the exact data returned: wallet balance, pay-per-use flag, license tier, per-action prices, purchasable and approved-but-unpaid plans. It also makes clear this is a multi-mode tool (read status, top up, request plan, complete payment), so an agent knows exactly what it is. No sibling in the list is billing-related, so no differentiation is needed.

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 states the operative scenario explicitly ('Use this to view or RESOLVE a 402 without leaving the connector') and then routes between the three modes by parameter: checkout_request_id to complete an approved plan, topup_amount to top up, request_plan to file a plan request. The when-to-use condition for each mode is unambiguous.

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 already covers the safety profile, and the description adds real context beyond it: it discloses that only the latest CIS/NIST cloud-policy scan is returned, that results include a company rollup, and the underlying data lineage (customers.Account.latest_scan -> compliances.ScanResults). No auth, rate-limit, or pagination detail, but meaningful disclosure for a read tool.

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?

One dense sentence, front-loaded with the purpose and followed by returned fields. The lineage arrow notation is terse but functional; nothing is wasted.

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?

There is no output schema, so the description carries the return-value burden and does so by enumerating compliance %, failing policies/records, status, and rollup. Input is fully covered. Adequate for a simple read tool, though sibling differentiation is still absent.

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 param at 100% schema coverage, the schema already documents account_id (including the 'all company accounts if omitted' behavior). The description restates that scoping but adds no syntax or format detail, 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+resource ('Cloud security & compliance posture') and details the returned content: compliance %, failing policies/records, status, and a company rollup. Scope (per cloud account plus rollup) is clear, though it never distinguishes itself from close siblings such as compliance_scan, compliance_status, 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 explains what data is retrieved but gives no when-to-use guidance and never names an alternative among the several overlapping compliance siblings. An agent must infer selection from the resource description alone.

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 already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety and external-call profile is covered. The description adds the returned field set (tracker, number, state, assignee), which is useful behavioral context, but says nothing about pagination, empty results, 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?

A single sentence that front-loads the resource and returned fields, then states the two scoping modes. No filler, no repetition of the title or annotations.

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 lookup with no output schema, naming the returned fields is a meaningful compensation. However, with 0% schema coverage and two optional parameters, the definition is silent on the default behavior when no arguments are given, on pagination, and on how the two redundant scoping inputs interact.

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

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

Schema description coverage is 0%, so the description must carry the load. It maps the two bare parameters to their roles ('threat entries' vs 'diagram'), which is genuine added meaning, but it never states that both are optional, whether they are mutually exclusive, or what happens when neither is passed.

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 a specific resource (tickets) and its scope conditions (for given threat entries, or for a diagram), plus previews the returned fields. Combined with the name, an agent can tell what it does, but nothing distinguishes it from siblings like file_threat_tickets, sync_threat_tickets, or list_ticket_destinations.

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

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

No when-to-use guidance, no prerequisites, and no alternatives named. The 'or for a diagram' clause hints at two input modes but never says which to choose or what happens if neither is supplied, leaving the agent to infer against three ticket-related 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 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description contributes only the caller-scoped framing and the ambiguous '(no credentials)' note, and it gives no clue whether results are paginated, filtered, or empty when no destinations exist.

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 compact sentence with no filler, and the resource enumeration is front-loaded. It is arguably too terse for its ambiguity, but nothing is wasted.

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 zero-parameter read tool with annotations carrying the safety profile and no output schema, the description is close to sufficient, but the term 'destinations' is never grounded (target systems? identifiers? configs?) and '(no credentials)' is left unexplained, so an agent cannot confidently describe what it will receive.

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 tool takes zero parameters, so the schema baseline of 4 applies and there is nothing further for the description to explain. No parameter-related gaps exist.

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 names the resource (trackers, routes, destinations) and its scope (those this caller may send threats to), which is informative, but it is phrased as a noun fragment rather than stating the action, and it never distinguishes itself from the closely named sibling file_threat_tickets. An agent can infer 'listing' from the tool name but not from the description alone.

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 and no reference to any alternative such as file_threat_tickets, which is the obvious downstream consumer of these destinations. The discovery-then-file workflow is only implied, never stated.

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 idempotency and non-destructiveness, so 'Idempotent' is partly redundant, but the description adds real behavioral context: a licence prerequisite and a manage:agents grant (or first-party super-admin). It still doesn't describe the response or what happens to already-onboarded agents beyond the idempotency claim.

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 dense sentences that are front-loaded with the core action, followed by input forms, then prerequisites. Every clause carries information, though the parenthetical field lists make it slightly heavy to scan.

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 four-param, no-required, mutation-style tool with no output schema, the description covers input forms, idempotency, licensing, and the self-onboarding fallback. Return behavior is unspecified, but with no output schema declared and a bulk upsert shape, an agent has enough to invoke it correctly.

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, but the description adds meaning the schema does not: it clarifies `agents` takes either plain ids or {agent_id} descriptors and reveals that MCP client descriptors are also accepted for a loosely-typed array, plus the A2A Card fields and the cohort auto-suspend policy. This goes beyond restating 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?

States a specific verb and resource — 'Bulk-onboard agent identities to the governed fleet (Agent Governance)' — and scopes it as a bulk operation. An agent can distinguish it from siblings like run_ai_governance_audit or discover_shadow_ai without opening any schema.

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?

Explains the accepted input shapes and that onboarding is optional because 'Agents also self-onboard on first token/call,' which implicitly tells the agent when this tool is unnecessary. It never names an alternative tool or an explicit when-not-to-call condition, so it stops short of a 5.

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, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds real value by disclosing what the audit produces — article-by-article conformity, satisfied controls, open gaps, and remediation guidance — which is useful given no output schema exists.

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 dense sentences with zero filler; the audit action and framework scope are front-loaded before the output description. Every clause 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?

With annotations covering the safety profile and no output schema, the description adequately covers inputs and the shape of the result. It could be slightly more complete by clarifying how diagram_id and scan_id combine, but nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description expands framework identifiers into human-readable names (EU AI Act 2024, DORA 2022, NIST AI RMF 1.0, ISO 42001) and implies cross-correlation via the scan_id mention, but adds no syntax or default guidance 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?

Specific verb ('Audit') plus two resources (architecture diagram or code scan) and a clear target (statutory AI governance frameworks). It distinguishes itself from generic siblings like compliance_scan, but never names an alternative to route against.

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

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

The description implies the audit use case but gives no explicit when-to-use, prerequisites, or comparison to siblings such as compliance_scan or get_framework_coverage. The agent must infer selection from the name alone.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), the description discloses batching limits (max 50, time-boxed), the exact return shape, pagination semantics via 'remaining', a rate_limited and permission_missing error surface, and idempotency/retry safety rules for specific error codes. That is unusually rich behavioral context for a state-mutating sync.

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?

Purpose, batching limit, and return contract are front-loaded, and the retry rules come last where they belong. The inline dump of ~20 error codes is dense and could have been grouped or deferred, but each code carries real recovery meaning.

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

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

For a no-parameter, no-output-schema, mutating sync against an external system, the description supplies everything an agent needs: what is fetched, the batch ceiling, the return contract, continuation logic, and per-error retry behavior. Nothing material is left implicit.

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 tool takes zero parameters and the schema is closed (additionalProperties: false), so there is nothing for the description to clarify. Baseline 4 applies; no parameter semantics are needed or missing.

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 a specific verb+resource: pulling the current state and assignee of the company's open tickets. It is clear what the tool does, but it does not differentiate itself from nearby siblings like get_threat_tickets or file_threat_tickets, which an agent could plausibly confuse with this sync operation.

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 gives concrete operational guidance: call again while remaining > 0, and how to handle retries (resend not_attempted, do not resend filed_unrecorded or outcome_unknown without checking the tracker). What is missing is guidance on when to prefer this tool over get_threat_tickets/file_threat_tickets.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false and openWorldHint=true; the description adds the genuinely useful behavioral fact that the call is synchronous with a threat_id but fans out into an asynchronous batch dispatch without one. That branch-dependent response shape is exactly the kind of context the annotations do not carry, though it never explains the side effect that makes this non-read-only.

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, zero filler, and the core purpose is front-loaded ahead of the branching behavior. Every clause 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?

With no output schema, the description does the necessary work of telling the agent that a threat_id yields an immediate verdict while the batch path returns a dispatch rather than results. It stops short of describing what a verdict contains, but for a 4-parameter tool with full schema coverage this is nearly complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the semantic consequence of threat_id's presence versus absence (sync verdict vs batch dispatch), which the schema merely calls 'Optional specific threat id/code to verify'. code_content and repository_id are left to the schema, which handles them adequately.

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) with the scope clearly bounded to a scan's uploaded code or AST. It is readily distinguishable from siblings like generate_threat_model or code_review_scan, though it never names an alternative to sharpen 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?

It gives conditional behavior (pass threat_id for a single synchronous verdict, omit it to batch-verify all diagram threats), which implies when each mode applies, but it offers no guidance on when to prefer this tool over siblings such as code_review_scan or generate_threat_model, and no stated prerequisites.

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