aribot

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real value on top: it names the governance gates (attack-path reachability, autonomy policy, approval flow) and discloses the 'requires_approval' no-op outcome, telling the agent it won't always mutate. It could go further on reversibility/scope but this is solid.

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 tight sentences with the core 'act for real' fact front-loaded, then the governance path, then the failure outcome. No filler; each sentence carries a distinct point.

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 governed mutation with no output schema, the description covers the key behavioral facts an agent needs: it acts live, it passes governance, and it may return 'requires_approval'. Naming the read sibling would close the last gap, but nothing essential is missing 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 description coverage is 100% with all three required parameters documented (including the nested resource_context members). The description adds no parameter-level detail, so the schema does the work; 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 specific verb and resource ('Apply a remediation for real') and the '(mode=live)' qualifier signals it performs the actual write, implicitly contrasting with a preview/read counterpart. It does not name the sibling get_remediation explicitly, so it's just short of full differentiation, but an agent can still tell this apart from the read side.

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 sets the context (governance checks, approval flow) and the outcome when approval is needed, which implies when it will act versus defer. However, it never explicitly routes the agent from alternatives like get_remediation or states when-not-to-use, leaving the choice to inference.

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 cover readOnlyHint=false and openWorldHint=true, but the description adds real value beyond them: the linked-ticket propagation behavior, and the meaning of replay-sensitive codes filed_unrecorded and outcome_unknown (ticket may already exist) plus not_attempted. This is exactly the non-idempotent context an agent needs. It stops at 4 because permission/role requirements and ordering are not described.

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?

Front-loaded clause is tight, but the body is one long error-code dump of 21 identifiers that swamps the actual purpose and buries the three explanatory sentences at the end. The enumeration consumes the majority of the text and is not grouped or scannable.

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

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

Covers the side effect and the ambiguous failure modes, which is genuine complexity for a mutation tool, but there is no output schema, no statement of return value, no auth/permission prerequisites, and params remain partly undocumented. Adequate but with clear gaps.

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 33%, so due_date is documented as YYYY-MM-DD, but threat_entry_id and assignee_member_id (including nullable semantics meaning 'unassign') are undocumented in both places. The description adds the meaning of the two fields being set but no per-parameter detail, so it does not compensate for the coverage gap.

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 ('Set the owner and due date of a threat entry') and adds a notable side-effect ('the linked ticket follows'). It does not differentiate from siblings like sync_threat_tickets or file_threat_tickets, so it stops 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?

No explicit when-to-use or when-to-avoid guidance, and no mention of alternatives such as sync_threat_tickets or file_threat_tickets. The error taxonomy implies context but never says when an agent should reach for this tool.

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

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

Annotations 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?

Well beyond the annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true), it discloses idempotency, the public-repository skip with its literal reason string, the per-comment return statuses (posted/updated/skipped/failed), and a full error-code vocabulary. It even disambiguates the ambiguous codes: 'filed_unrecorded and outcome_unknown mean the ticket may already exist in the tracker; not_attempted means the item was not sent.'

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?

Core behavior, skip rules, and return semantics are front-loaded in the first two sentences, with the error vocabulary batched at the end where it belongs. The error-code enumeration is long but most of it is load-bearing; a couple of the codes receive no gloss and pad the list slightly.

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 takes on the burden of explaining return values, and it does so by enumerating per-comment statuses and the reason strings for skips and failures. Combined with the destination rules and error glossary, an agent has everything needed to call and interpret this 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% for the single scan_id parameter, so the schema already carries the parameter documentation and 3 is the baseline. The description adds only that the id must reference a completed pipeline scan of a pull request, a modest amount of context beyond the schema's 'Pipeline scan id (uuid)'.

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

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

The description states a precise verb pair (post, or update) against a precisely scoped resource (one comment per threat whose linked code the pull request changes), plus the precondition of a completed pipeline scan. That scope distinguishes it cleanly from siblings such as file_threat_tickets and get_threat_tickets without needing to name them.

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 a clear activation condition ('For a completed pipeline scan of a pull request') and calls out idempotent re-run behavior ('a re-run with nothing changed makes no calls'), which is exactly the guidance an agent needs before retrying. It does not, however, name an alternative tool or state when not to use this one versus the ticket-filing 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?

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

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

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

The description is two sentences that directly convey the core purpose, async behavior, and return value. Every sentence is efficient and relevant, with no wasted words.

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

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

The description explains the return value (task id) since no output schema exists, but it lacks detail on polling or interpreting results. With 7 parameters and many siblings, the description could provide more context on distinguishing from related tools.

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

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

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

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

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

The description clearly states the tool runs a cloud/platform or compliance scan against an account or diagram, with specific scan types enumerated. It distinguishes the tool's async nature and return of a task id, making its purpose unambiguous.

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

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

The description implies usage for initiating scans but does not provide explicit guidance on when not to use this tool or mention alternative tools like compliance_status or get_cloud_compliance for checking results. The context is clear but lacks exclusions.

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

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

Annotations already establish the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false). Beyond that, the description discloses data provenance and cadence ('daily cloud scans', 'code scans'), the shape of returns (checks passed/failed, controls tested/failing), and the unit convention for rates (percentages 0-100), which the annotations cannot convey. Pagination/limits remain unstated.

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 earning its place: what it returns, how to narrow by framework, and the rate units. What the tool is leads, invocation guidance and units follow — no filler.

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

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

With no output schema and no required params, the description must carry the return-value burden, and it does describe the key contents (per-framework checks/controls plus code-scan metrics). It is close to complete, though it doesn't clarify how scan_id and diagram_id scope the results or whether cloud and code-scan data are merged or separate sections.

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 genuine semantics beyond the schema: the `framework` argument doesn't just filter, it switches the view to that framework's most-failing controls. That behavioral effect on output is not in the schema. scan_id and diagram_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 resource and scope: 'Company-level compliance posture: per-framework posture from the daily cloud scans... plus threat and control metrics from code scans.' An agent can tell it is a read-only aggregate view. It stops short of naming how it differs from close siblings like get_cloud_compliance or get_framework_coverage, leaving some ambiguity about which aggregate to pick.

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

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

Usage is implied rather than stated: the description gives one concrete invocation ('Pass `framework` ... to get that framework's most-failing controls'), which is a param hint more than a when-to-use rule. It never says when to prefer this over get_cloud_compliance, get_framework_coverage, or compliance_scan.

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?

Annotations only declare readOnlyHint=false, openWorldHint=true, destructiveHint=false; the description goes well beyond that. It discloses idempotency ('a repeat returns already_filed'), dry-run semantics, the visibility risk of publishing to a public repository, and partial-failure semantics ('filed_unrecorded and outcome_unknown mean the ticket may already exist in the tracker'). Rate limiting and permission-style failures are also surfaced via error codes, though the codes themselves are mostly unexplained.

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 and its scope are front-loaded in the first sentence, followed by mapping/idempotency semantics. The trailing 17-item error-code list is dense and largely unglossed, consuming roughly half the text, but it is informationally useful for error handling rather than filler.

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

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

With no output schema and openWorldHint=true, the description carries return-value burden and does so: it explains dry_run returns exact tickets, repeats return already_filed, and lists failure codes including ambiguous-outcome cases. Missing pieces are the public_repository reference that has no matching parameter and no explanation of most error codes' remedies.

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%, so the description must compensate, and it largely does: it documents the 1-50 bound on threat_entry_ids, the dry_run preview behavior, and the destination-as-route-override purpose. The schema describes destination as '{provider, channel_ref, destination}' but the description introduces 'public_repository=true', which appears nowhere in the schema, creating a small ambiguity.

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 and resource with scope: 'Send 1-50 threat report entries to the tracker their route points at (or `destination`)'. It also conveys the one-ticket-per-threat model, telling the agent how entries map to tickets. It never names or contrasts the closest siblings (sync_threat_tickets, get_threat_tickets, list_ticket_destinations), so the agent must infer 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?

It gives useful invocation context: dry_run for previewing exact tickets, and public_repository for previewing against a public repo. But there is no explicit when-to-use-this-vs-alternative guidance against sync_threat_tickets or get_threat_tickets, and no stated prerequisites such as required role or permissions. Usage is implied rather than routed.

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, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the operation runs asynchronously in the background for a few minutes and returns the name the diagram is saved under, which is critical for an agent to know before waiting on it.

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

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

Two sentences, front-loaded with the core capability and immediately followed by the runtime/return behavior. No filler or restatement of the tool name.

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

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

With no output schema, the description correctly fills the gap by stating the return value (the saved diagram name) and the async runtime. The one remaining gap is the absence of any routing guidance versus the overlapping generate_threat_model sibling, which the description leaves unresolved.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, including the enum values for style and cloud_provider and examples for compliance_standards. The description only reinforces that the input is a natural-language description and says nothing extra about name, style, or save_as_diagram, 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 specific verbs and resources: generates a multi-tier cloud/AI architecture and synthesizes STRIDE/LINDDUN threat models, security requirements, and regulatory control mappings from a natural-language description. It is clear what the tool produces, but it does not differentiate itself from the sibling generate_threat_model, which appears to overlap on threat-model generation.

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 trigger condition is implied: you supply a natural-language description and get an architecture plus threat models. There is no explicit guidance on when to choose this over generate_threat_model, generate_architecture's sibling, nor any stated prerequisites or exclusions.

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

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

Annotations already establish that this is a non-read-only, non-idempotent mutation with no destructive or open-world risk. The description goes beyond that by disclosing the concrete side effects (Aribot stores the components, generates the threats) and the return value (diagram id), which is valuable since no output schema exists. It still omits that repeated calls create new diagrams rather than updating, which is the practical consequence of idempotentHint=false.

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 tight sentences with no filler; the action and input format are front-loaded and the return value is stated last. Slightly terse given no alternatives are mentioned, 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 3-param mutation tool with full schema coverage and no output schema, the description covers the input contract and the return value plus the side effect. The main gap is the absence of any guidance about re-generation/idempotency behavior.

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

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

Schema description coverage is 100%, so name, edges, and nodes are already documented by the schema, including the node shape (id, position, data.label). The description's 'ReactFlow nodes + edges' phrasing reinforces but does not extend that, 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 specific verb (Create) and resource (threat model) plus the exact input shape (normalized architecture of ReactFlow nodes + edges). An agent can tell this is the threat-generation step, but the description never explicitly distinguishes it from siblings like generate_architecture, leaving that contrast 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 description implies a precondition (input must be a normalized architecture) but gives no explicit when-to-use guidance, no when-not conditions, and never names an alternative tool such as generate_architecture or verify_threats_in_code.

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=false, so the safety profile is covered. The description usefully adds the payload shape (execution states running/held/suspended, deviation score, hold reason, totals by state), but says nothing about pagination, ordering, or freshness.

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 with zero filler, and the resource identity is front-loaded before the field enumeration. Slightly list-heavy, but every clause adds 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 carries the return-value burden and does so well by naming the exact fields and the aggregate. Missing only pagination/limit behavior and any indication of when the fleet view should be preferred over audit or remediation tools.

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

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

Schema description coverage is 100% with default/max documented for limit and optional filters for state and cohort, so the schema carries the parameter burden. The description adds no syntax detail beyond what the schema provides; 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 (governed AI-agent fleet) and enumerates the returned fields (id, name, cohort, active flag, execution state, deviation score, hold reason). This clearly distinguishes it from siblings like get_shadow_ai or get_remediation, though it never names an alternative.

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 routing to alternatives such as run_ai_governance_audit or get_shadow_ai. Usage is only implied by the resource name.

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=false, so the safety profile is covered structurally. The description adds the scope behavior (company-wide vs. single scan) and the shape of the returned inventory, but says nothing about auth requirements, rate limits, or pagination behavior beyond `limit`.

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, front-loaded with the resource and its contents, followed by the scoping rule. The parenthetical placement is slightly awkward 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?

With no output schema, the description carries the return-value burden and does so adequately by listing authentication status, risk level, risk factors and the method/risk breakdowns. Combined with the two-parameter schema and read-only annotations, an agent has enough to call 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 description coverage is 100%, so both parameters are already documented, and the description's 'company-wide if omitted' note merely restates the scan_id schema text. Baseline 3 applies since the schema does the heavy lifting and the description adds no new parameter 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?

States a specific resource (API security inventory) and enumerates its contents: discovered API endpoints with authentication status, risk level, risk factors, plus method/risk breakdowns. It is clearly distinguishable from siblings like get_code_findings or get_shadow_ai by the API-endpoint scope, though it never names an alternative explicitly.

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 final clause 'Company-wide or one scan with `scan_id`' tells the agent the two scoping modes, and the parenthetical 'part of Code Security' situates it in the product. There is no when-to-use vs. when-not guidance and no alternatives named among the many sibling read tools.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true with destructiveHint=false, so the mutation/network profile is known. The description adds substantive context beyond that: request_plan files a request and 'never grants', topup/checkout return a hosted Stripe URL, and the call is a resolution path for 402s. It does not cover idempotency or whether filing duplicate requests is harmful.

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 paragraph that front-loads what the tool returns, then walks through the three optional modes in call order. Every clause carries information, though the enumeration of return fields is slightly heavy for a tool whose schema is the only other structure available.

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 returned fields and framing the call as a 402 resolution. All three optional parameters are explained. Minor gap: no statement on how the three modes interact if passed together, or what happens on a rejected request.

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, and the description exceeds it: it gives the EUR unit for topup_amount, clarifies checkout_request_id must reference an already-approved plan, and supplies a fuller enum set for request_plan (starter|pay_per_use|pro|max|enterprise) than the schema's abbreviated 'pro|max|…'.

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+resource pairing (billing status plus self-service payment) and enumerates exactly what is retrieved: wallet balance, pay-per-use flag, licence tier, per-action prices, purchasable plans, unpaid approved plans. It is unambiguous and easily distinguished from every sibling tool in the list.

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

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

It clearly states the trigger conditions for each mode: passing checkout_request_id to COMPLETE an approved plan, topup_amount to TOP UP, request_plan to REQUEST. It also names the concrete problem this solves (resolving a 402 licence/credit error). It stops short of naming alternative tools or when *not* to call it, but no sibling competes for this purpose.

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

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

Annotations already establish the safe-read profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real value by disclosing the returned content: daily-scan pass/fail posture, the last manual scan's compliance percentage, failing policies/records, and a company rollup — all useful context given there is no output schema.

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 resource and scope before enumerating returned data. It is information-rich without padding, though the parenthetical "(Cloud Compliance)" and the nested enumeration of scan types make it slightly heavy.

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 well, spelling out both the per-account data and the company rollup. Combined with annotations covering the safety profile and a fully documented single parameter, an agent has everything needed to call 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?

There is a single optional parameter and schema description coverage is 100%, with the schema already stating that account_id limits results to one account and that all company accounts are returned when omitted. The description adds no parameter detail, so the baseline 3 applies — 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?

The description names a specific resource (cloud security & compliance posture) and scopes it precisely: per connected cloud account, CIS/NIST cloud-policy scans, daily-scan checks passed/failed, last manual scan compliance %, and a company rollup. It is clearly a read of cloud-specific compliance posture, which separates it from generic siblings like compliance_status and get_framework_coverage, though it never names those siblings explicitly.

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

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

Usage is implied rather than stated — an agent can infer this is the tool for cloud-account compliance posture, but there is no explicit when-to-use/when-not guidance and no routing to compliance_scan, compliance_status, or get_framework_coverage, which are the obvious overlapping siblings in this toolset.

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=false, so the safety profile is covered by structured data rather than the prose. The description adds the default-scan behavior and the shape of returned data, but says nothing about pagination, ordering, truncation at the limit, or what happens when no scan has completed. Adequate but not rich.

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

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

Two sentences, no filler. The resource and returned fields come first, and the default-resolution rule is placed last where it belongs as a fallback condition. Every clause carries 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 compensates by listing the fields a finding contains, so an agent knows what comes back. It also covers the scan_id default and the four filters. What is missing is minor: result ordering, total counts, and behavior when the filter set matches nothing.

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 and the schema already documents limit, status, scan_id, and severity. The description still adds meaning the schema omits: that an absent scan_id resolves to the latest completed scan, which is a default the schema's 'Optional code-security scan id' does not state.

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 resource (findings from a code-security scan) and scopes it by origin (SAST, secrets, dependencies), then enumerates exactly what each finding carries: title, severity, file/line, CWE/OWASP, status, fix. That level of detail distinguishes it from neighbors like get_remediation, get_threat_tickets, and compliance_scan without needing to name them.

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 supplies one useful selection rule — omit scan_id to get the latest completed scan — which tells the agent how to call it in the common case. It gives no guidance on when to prefer this over get_remediation (which appears to carry the fix) or code_review_scan, and offers no exclusions. Usage is implied rather than argued.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the bar is lower. The description adds content-level transparency by enumerating what the summary contains, which is useful given there is no output schema. It says nothing about data freshness, permissions, or cost, so it is solid but not rich.

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

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

A single tight sentence with zero filler, and the return contents are front-loaded after the subject. It is efficient but terse to the point of being a bare list, with no verb establishing the 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?

For a simple single-parameter read tool with full annotation coverage and no output schema, the description enumerates the returned fields well enough for an agent to know what it will get. It omits sourcing of the diagram_id and any scoping constraints, which are the only real gaps.

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 documents diagram_id as 'Diagram id/uuid'. The description's 'of a diagram' only restates the schema's meaning without adding format, source, or retrieval hints (e.g. where ids come from). Baseline 3 applies.

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

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

The description names the resource (a diagram) and the specific payload of the result: threat counts by severity, risk value, compliance and framework coverage. That is far more specific than a tautology and differentiates it from a generic summary. It does not name how it differs from near-neighbours like get_framework_coverage or compliance_status, so it stops 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 or when-not-to-use guidance and no alternative tool is named. The agent must infer that this is a follow-up call after list_diagrams, purely from the singular 'a diagram' phrasing. This mirrors the MID calibration, where absent routing guidance earned a 2.

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=false, so the safe read-only nature is covered. The description adds useful output context (coverage percentages, gap counts, mapped controls) but no additional behavioral details such as permissions, scoping to diagrams, 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, front-loaded sentence with zero filler. It states the verb, the returned data, and the framework scope immediately.

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

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

No output schema exists, so the description must explain return values, and it does so by naming coverage percentages, gap counts, and mapped controls. It does not explain that results are scoped to a diagram or describe pagination, but it is largely complete for a simple read tool whose safety profile is covered by annotations.

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

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

Schema description coverage is 100%, so the schema already documents framework, diagram_id, and include_graph. The description names additional frameworks such as SOC 2, but this only marginally extends the framework parameter examples and adds no meaning for the required diagram_id or include_graph parameters. 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 specific verb and resource ('Get control-mapped coverage percentages, gap counts, and mapped controls') and lists the compliance frameworks covered. This clearly describes the tool's function, but it does not explicitly differentiate it from sibling tools such as compliance_status or get_cloud_compliance.

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

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

The description provides no when-to-use guidance, prerequisites, or mention of alternatives. It implies a coverage-reporting purpose through the name and phrase 'control-mapped coverage,' but offers no routing information for an agent choosing among the many compliance-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 already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds genuine behavioral context by disclosing the null edge case for code_scan when a diagram has no scan, which the agent could not infer from annotations or schema.

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 tight sentences, with the primary payload (what metrics are returned) front-loaded and the edge case appended. Nothing repeats the tool title or wastes space.

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 work of sketching the return shape (threat → finding → control metrics, latest scan) and the null state. It covers what an agent needs to call and interpret the tool, though it omits any note on scan staleness or metric units.

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?

Only one parameter (diagram_id) with 100% schema description coverage, so the schema already carries the semantics. The description adds no format, constraint, or id-resolution detail beyond it; baseline 3 applies.

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

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

The description names a specific resource (code-security metrics for a diagram) and unpacks the metric categories it returns (threat → finding → control) from the latest scan. That scope is distinctive enough to separate it from siblings like get_diagram_summary or get_code_findings, though it never explicitly contrasts itself with them.

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 alternatives named, despite a large sibling set (get_diagram_summary, get_code_findings, compliance_status) that an agent could easily confuse with this. Usage is only implied by the resource description.

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=false, so the safety profile is covered. The description adds value by confirming the dry-run semantics and noting that it runs governed checks and returns proposed steps, though it says nothing about cost, latency, or failure modes.

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 tight sentences, front-loaded with the core action and the non-destructive qualifier. No filler or restatement of the title.

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

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

No output schema exists, and the description does note that it returns proposed steps, which covers the return intent. For a 3-required-param tool with a nested resource_context object, it is adequate given the schema already documents inputs in full.

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 all three parameters (rule_id, threat_id, resource_context) are already documented in the schema, including the nested resource_context fields. The description adds no additional parameter meaning, 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 (compute), resource (remediation plan), and scope (for a threat or finding, dry run). The phrase 'without applying it' immediately distinguishes it from the apply_remediation sibling without needing to name it.

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?

Clear context for use: to preview remediation steps for a threat or finding before committing. The dry-run qualifier implicitly routes the agent away from apply_remediation, but the sibling is never named and no explicit when-not guidance is given.

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 cover readOnlyHint, destructiveHint, and openWorldHint, so the safety profile is set. The description goes further by disclosing that entries carry a mode (dry run or live), a status/outcome, and that it also reports whether autonomous live remediation is enabled for the company — meaningful context beyond the structured fields.

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

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

A single dense sentence that front-loads the resource ('Remediation (self-healing) history') and then the field inventory. It is information-rich with little waste, though the field list is packed tightly.

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 usefully enumerates the returned fields (threat, rule, resource, mode, status, outcome, autonomy flag), which compensates for the missing return spec on a read-only tool. It stops short of describing pagination or the shape of the autonomous-remediation flag.

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

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

Schema description coverage is 100%, so the schema already documents mode (dry_run/live), limit, and status. The description restates mode as 'dry run or live' but adds no syntax, default, or filtering behavior beyond what the schema provides; 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 specific verb and resource: retrieval of remediation (self-healing) history, enumerating the fields each entry carries. It clearly describes what the tool returns, but it never distinguishes itself from the very close sibling 'get_remediation', leaving an agent to guess which history endpoint to call.

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 an audit/history use case but gives no explicit when-to-use guidance and names no alternatives. With siblings like get_remediation and apply_remediation adjacent, the agent gets no routing signal for this tool versus them.

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=false, so the safety profile is covered. The description adds useful context about content (company-wide vs single-scan scope, hard-coded key detection), but says nothing about pagination, result caps beyond the schema, or freshness of the data.

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 with high information density; the field enumeration is front-loaded and the scoping note closes it. It is efficient, though the opening noun phrase is slightly less direct than a verb-first statement would be.

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 return values and does so by listing the discovery fields, which is genuinely useful. It is nearly complete for a read-only retrieval tool, with the only real gap being the relationship to discover_shadow_ai.

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 limit, scan_id, and risk_level are fully documented in the schema, making 3 the baseline. The description only reinforces scan_id's scoping role and adds no syntax or semantic detail beyond what the schema already provides.

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

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

The description states the resource clearly — 'AI usage found in your code and network traffic' — and enumerates the concrete fields returned (provider, model, endpoint, risk level, hard-coded key). It implies a retrieval tool, but never states the verb and does not explicitly distinguish itself from the sibling discover_shadow_ai, which a reader could easily confuse it with.

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 trailing clause 'Company-wide, or one scan with scan_id' gives some scoping guidance and implies when to pass a scan_id. However, it never states when to use this tool versus discover_shadow_ai (discovery vs retrieval), which is the key ambiguity given the sibling 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that the response carries ticket tracker/number/state/assignee, which is useful since there is no output schema, but it says nothing about behavior when neither or both parameters are supplied, or about result ordering/emptiness.

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 the returned fields named first and no filler. It is efficient, though its terseness borders on under-specification rather than true economy.

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 and no parameter descriptions, the description covers what is returned and the two input modes. It still leaves gaps on how the two optional parameters interact and what happens with an empty or omitted selection, so it is adequate but not 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 description coverage is 0% and both parameters are undocumented in the schema, so the description must compensate. It loosely maps the two parameters to two modes ('threat entries' vs 'a diagram') but adds no format, mutual-exclusivity, or default behavior detail, leaving the semantics only partially covered.

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 the two scopes it can be fetched for (threat entries or a diagram), and it enumerates the returned fields (tracker, number, state, assignee). It does not explicitly distinguish itself from siblings like file_threat_tickets or sync_threat_tickets, but the retrieval framing is clear enough.

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 implies two usage modes via 'for the given threat entries, or for a diagram', which hints at when each parameter applies. However, it never states when to prefer this over siblings such as file_threat_tickets or sync_threat_tickets, and gives no exclusions or prerequisites.

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 establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value beyond that: it discloses the exact shape of the returned artifact (the full traceability chain) plus that coverage metrics are included, which tells the agent this is a read-only aggregation rather than a raw record fetch.

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 verb and the returned chain, then appends the coverage-metrics detail. Every clause carries information and there is no filler.

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

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

For a one-parameter, read-only aggregation with no output schema, the description conveys what comes back well enough for correct invocation. Minor gaps remain: 'coverage metrics' is undefined and 'in your scope' is left implicit rather than stated as a permission or filtering boundary.

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% for the single scan_id parameter, so the schema already documents the input. The description adds only the scoping notion ('a scan in your scope') and no format, id source, or constraint details beyond the schema, so the baseline of 3 applies.

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

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

The description names a specific verb ('Return') and a highly specific resource (the diagram→threat→finding→control→requirement→remediation traceability matrix). The enumerated chain is distinctive enough to separate it from near neighbors like get_diagram_summary, get_code_findings, and get_framework_coverage, and 'for a scan in your scope' pins the unit of work.

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 phrase 'for a scan in your scope' implies the usage context (per-scan, within the caller's scope), which is useful, but there is no explicit when-to-use, when-not-to-use, or named alternative such as get_framework_coverage for compliance-style views. Usage is inferable rather than 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real behavioral context beyond the schema: results are scoped to the caller's company and sorted newest first. It does not describe pagination/truncation behavior, keeping it short of a 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?

A single sentence, front-loaded with the verb and resource, then scoping, return fields, ordering, and the optional filter. 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?

No output schema exists, but the description enumerates the returned fields (id, name, last update) and ordering, which compensates. Minor gap: nothing about total counts or how the limit interacts with large result sets, so an agent has to assume truncation.

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%: both 'name' (part of the name) and 'limit' (default 20, max 100) are fully documented in the schema. The description only echoes the name filter, 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?

States a specific verb ('List') and resource ('threat-model diagrams'), scopes it to the caller's company, and names the exact fields returned (id, name, last update) plus ordering (newest first). An agent can distinguish this from sibling get_diagram_summary which returns a single diagram's detail.

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

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

Usage is implied by 'optionally filtered by part of the name' and the newest-first ordering, which signals a browsing/discovery use case. However, it never states when to prefer this over get_diagram_summary or other listing siblings, nor any exclusion. Baseline implied-usage score.

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=false, so the safety profile is covered. The description adds that these destinations require no credentials, which is useful behavioral context, but it does not disclose return format, pagination, or other operational details.

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 compact phrase that front-loads the returned resource and includes a useful parenthetical about credentials. It is appropriately sized for a simple read-only list tool, though the fragmentary phrasing is slightly terse.

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-only list tool whose annotations already cover safety, the description is largely complete: it names what is returned and notes that no credentials are involved. It does not describe return structure or pagination, but those omissions are minor given the tool's simplicity.

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

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

The tool has zero parameters, so the baseline is 4. There are no parameter semantics for the description to clarify beyond what the empty schema already establishes.

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 identifies the resource as trackers, routes, and destinations that threats can be sent to, and clarifies the caller-scoped nature. It is clear enough to understand the tool's subject, but it does not explicitly differentiate it from sibling threat-ticket tools or state the listing action in prose.

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 explicit guidance on when to use this tool versus alternatives such as file_threat_tickets, sync_threat_tickets, or get_threat_tickets. The description implies context by mentioning destinations this caller may use, but it provides no when/when-not conditions.

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 establish readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond that: the audit is article-by-article and produces satisfied controls, open gaps and remediation guidance, which tells the agent what the call yields. No contradiction with the read-only annotation, since generating a report is not a state mutation.

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, no filler, with the action and scope front-loaded ahead of the output inventory. Slightly run-on but every clause carries 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 usefully enumerates what the audit returns (article-level conformity, satisfied controls, gaps, remediation). For a read-only tool with full schema coverage and annotations, that is close to complete. The remaining gap is prerequisite/routing information, e.g. how a diagram_id is obtained or why this differs from compliance_scan.

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 all three parameters are already documented, including the framework enum values and the optional scan_id. The description's framework list roughly mirrors the schema's framework parameter but adds no syntax, defaulting behavior or interaction detail (e.g., how scan_id cross-correlation affects results). 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?

Specific verb (audit) plus two accepted inputs (architecture diagram or code scan) and a named resource class (statutory AI governance frameworks). The parenthetical list of EU AI Act / DORA / NIST / ISO concretely bounds scope. It does not, however, distinguish itself from the sibling compliance_scan or get_framework_coverage, which is the only thing keeping it from 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?

Usage is implied by the accepted inputs and the framework list, so an agent can infer 'call this when you have a diagram_id and need a regulatory audit.' But there is no explicit when-to-use statement, no exclusions, and no routing away from the near-identical siblings compliance_scan and get_framework_coverage.

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, it discloses batching (max 50 per call), time-boxing, the return fields and their meaning, and semantic explanations for the risky error codes (filed_unrecorded/outcome_unknown mean the ticket may already exist; not_attempted means not sent). The gap is that readOnlyHint=false implies a write-back, but the description only describes pulling state.

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 return semantics are front-loaded and efficient, but the 19-item error-code dump is a low-signal enumeration that bulks up the text without explaining most codes. Only three of the codes receive any interpretation.

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 and no parameters, the description supplies the return shape and pagination contract the agent needs. It is nearly complete, only falling short on clarifying what the sync actually mutates given readOnlyHint=false and openWorldHint=true.

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 schema coverage is trivially complete; the baseline for a 0-param tool is 4. The description correctly notes the company scoping is implicit rather than passed as an argument.

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?

"Pull the current state and assignee of this company's open tickets" gives a specific verb+resource with scope (open tickets, this company). However, it does not differentiate itself from the sibling get_threat_tickets, and the word "Pull" underplays the sync/write-back implied by the name and readOnlyHint=false.

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 only usage guidance is the pagination cue ("remaining > 0 means call again to continue"). There is no statement of when to call this versus get_threat_tickets or file_threat_tickets, no prerequisites, and no exclusions.

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

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

Annotations only 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.