Mipiti MCP Server
Server Quality Checklist
Latest release: v0.68.2
- Disambiguation4/5
Each tool targets a distinct resource+action pair, and near-pairs (assess_model vs check_control_gaps, recompute_verdicts vs retry_verdicts, get_review_queue vs list_findings) are explicitly cross-disambiguated in their descriptions. However, at 129 tools the sheer volume of get_*/list_*/set_* surfaces creates real misselection risk, especially among the several overlapping triage/status surfaces.
Naming Consistency4/5The set is predominantly snake_case verb_noun with strong pattern discipline (get_, list_, add_, edit_, set_, delete_, remove_, submit_, import_ all used predictably). Minor inconsistencies exist: add_ vs create_ both signal creation, delete_ vs remove_ both signal soft-deletion (delete_control and remove_entity are both soft-deletes), and edit_ vs update_ both signal modification, which slightly blurs the convention.
Tool Count2/5129 tools is far beyond the ergonomically reasonable range for agent tool selection, exceeding the 25+ threshold for 'too many' even accounting for the server's genuinely broad scope (threat modeling, compliance, composition, functional testing, verdicts, groups). The count verges on extreme mismatch, but the domain breadth is real and each tool maps to a distinct backend operation, so it stops short of a 1.
Completeness4/5The surface is exceptionally complete: full CRUD for every entity type, batch operations (apply_control_changeset), background-job polling, preview-then-apply remediation flows, and explicit chaining between tools. Minor documented dead ends exist — system groups cannot be deleted or have members removed, and a few 'only removal path' boundaries (no pause toggle on reliance) — but agents can work around these.
Average 4.5/5 across 125 of 129 tools scored. Lowest: 2.8/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 64 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add
glama.jsonto the root of your repository:{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": [ "your-github-username" ] }Then . Browse examples.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose all behavioral traits. It mentions the side effect of creating a new model version but does not describe any destructive actions, required permissions, or other behaviors such as whether the operation can be undone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) but could be improved by adding more context without becoming verbose. It is front-loaded with the main action, but the brevity sacrifices informativeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters and a domain-specific concept (trust boundary), the description lacks sufficient context. It does not explain what a trust boundary is, how it relates to the model version, or what the output schema contains. An output schema exists but is not shown, so the description carries responsibility for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has high description coverage (83%), so the baseline is 3. The tool description itself adds no parameter-specific information beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool adds a trust boundary and notes the side effect of creating a new model version. However, it does not differentiate from similar tools like edit_trust_boundary beyond the verb 'add', and the term 'trust boundary' is not defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives (e.g., edit_trust_boundary, remove_trust_boundary). There is no mention of prerequisites or context for its use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details inheritance behavior, composition effects, and the return shape including conditions for empty results. However, without annotations, it fails to disclose authentication requirements, rate limits, or potential side effects. It adds value beyond the schema but is incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed and includes a code block for the return shape, which is helpful but somewhat lengthy. It is well-structured but could be more concise without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity and the presence of an output schema, the description provides a thorough explanation of the return shape and behavior under composition. It addresses edge cases (composition disabled) but lacks prerequisites or error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%, with only model_id having a description. The tool description adds no further explanation for server_version, which lacks a description. It does not compensate for the missing schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool lists 'Effective AttackPath set' and mentions 'suggestions' for missing/dangling paths. It differentiates itself from siblings like list_effective_entities by focusing on attack paths. The purpose is clear but could be more concise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide when to use this tool over alternatives or any prerequisites. The usage context is implied from the tool name and description, but no explicit guidance is given for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Explains the criteria for return values (controls not reviewed in 90+ days, implemented/verified, assertions not checked), but lacks details on side effects, authentication needs, or output format, with no annotations to supplement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, no unnecessary words or fluff, and front-loads the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a required parameter and no annotation support, the description is incomplete as it omits parameter semantics entirely, despite having an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description makes no mention of the required parameter 'server_version', and the schema provides no description, leaving the agent without guidance on what value to supply.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns controls not reviewed in 90+ days, specifying implemented/verified controls whose assertions have not been checked recently, distinguishing it from sibling tools like get_controls.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage is for finding stale controls to verify assertions against codebase, but no explicit guidance on when to use this tool versus alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does add a meaningful behavioral trait ('Creates a new model version'), which is a side effect not obvious from the schema. However, it omits other relevant traits such as required permissions, reversibility, or implications for model state. This is more than a tautology but far from comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short, efficient sentences. Each sentence earns its place: the first states the primary purpose, and the second conveys a crucial side effect. There is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and a high-coverage input schema, the description is mostly complete for invocation. It conveys the essential non-obvious behavior (version creation) and the core purpose. However, it could additionally note when to use versus sibling assumption tools or any constraints, so it is slightly above minimum viable but not fully rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 92%, so the input schema already documents the parameters in detail. The description itself adds no parameter-specific meaning or additional context beyond what is already in the schema. Baseline 3 applies given the high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Edit an assumption') and identifies the resource, with a specific verb. It also mentions the key side effect of creating a new model version, which distinguishes it from sibling tools like add_assumption, remove_assumption, and restore_assumption.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that add_assumption is for new assumptions, remove_assumption for deletion, or any conditions that might make editing inappropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It adds valuable context about group logic but does not disclose safety traits like idempotency, side effects, or permissions. Being a GET tool, it's likely safe, but this is not stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded, and wastes no words. Every sentence adds value, explaining both the action and the logical structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, return values need not be explained. The description covers the concept well. However, it lacks prerequisites or error conditions, but for a simple retrieval, it is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%, with two parameters described in schema. The description adds no parameter-level information. For the uncovered 'server_version', no help is given. Baseline 3 is appropriate as schema does most of the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets the assumption group structure for a control and explains the AND/OR logic. However, it does not explicitly differentiate from sibling 'get_*_groups' tools, though the name is specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like set_control_assumption_groups or get_mitigation_groups. Usage is implied but not contrasted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description details the return format and an edge case (disabled status). It clearly states that a disabled state is normal, not an error. However, it omits information about authentication or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences), front-loaded with the main purpose, and efficiently conveys necessary information without extraneous details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the return format and a special case, but lacks explanation of the input parameter. Given the output schema exists, the return details are complete, but the input omission reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the sole parameter 'server_version'. With 0% schema description coverage, the agent receives no guidance on what value to provide, which is a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and the resource ('CWE reference catalog status'). It distinguishes itself from siblings that perform other actions (e.g., classification, exporting).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The name implies its purpose, but there is no mention of conditions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that a new model version is created, which is a key side effect. However, it lacks details on permissions, reversibility, or other consequences, such as triggering recomputation or audit trail requirements hinted in the 'change_reason' parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loaded with the main action. Every sentence adds value, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters and an output schema, the description is too brief. It does not explain prerequisites (e.g., trust boundary must exist), error conditions, or the implications of creating a new model version. The output schema likely covers return values, but overall context is minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 89% (high), so baseline is 3. The description adds no additional meaning beyond what the schema provides. It does not mention or explain any parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it edits a trust boundary and creates a new model version. The verb 'Edit' and resource 'trust boundary' are specific, and the added context of creating a new version distinguishes it from siblings like 'remove_trust_boundary' or 'get_trust_boundary'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'add_trust_boundary' or 'remove_trust_boundary'. It only states what the tool does, leaving usage context implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses billing, duration, and that refresh replaces prior generated content (not manual). No annotations provided, so description carries the full burden; it addresses key behavioral aspects well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two paragraphs, clear first sentence, no fluff. Could be slightly more front-loaded, but overall efficient for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers process (walking conditions, producing Given-When-Then, specifying tests), prerequisites (Pro plan), and side effects (replacement on refresh). Has output schema, so return values are handled. Adequate for a complex generation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, with descriptions for model_id and refresh. Description adds context for refresh (re-derives, replaces) but does not describe server_version. Adds marginal value over schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action: derive capabilities, functional objectives, and tests from a feature spec. Distinguishes from sibling listing tools like list_capabilities and list_functional_objectives by focusing on generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use when generating from a feature spec, mentions Pro plan requirement, billing, and time. Does not explicitly contrast with other generation tools or provide when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool is read-only and fast, composes from existing per-model queries server-side, and returns an envelope verbatim with specific fields. This covers key behavioral traits for a read operation. Could mention rate limits or data freshness, but overall sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, starting with the purpose, then usage guidelines, then return envelope details. It is concise without unnecessary repetition, though it could be slightly shorter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity and the presence of an output schema, the description mostly suffices. However, the failure to explain the only input parameter is a notable gap. The description otherwise gives a complete picture of what the tool does and its return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has one required parameter (server_version) with no schema-level description (0% coverage). The description does not mention this parameter at all, failing to add any meaning. With such low schema coverage, the description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a workspace-scoped triage dashboard that returns open findings, active risk acceptances, and at-risk Control Objectives. It contrasts with sibling tools like list_findings or list_risk_acceptances by offering a consolidated entry point for 'what's open?' queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using this as the entry point when an operator asks 'what's open?' or 'what should I work on next?'. It emphasizes that one round-trip returns all three categories, implying this is faster than using separate tools. Does not mention explicit when-not-to-use scenarios, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries full burden. It discloses the return shape with origin classification, and the edge case when composition is disabled (returns empty list and flag_enabled: false). It does not explicitly state that it is read-only, but the nature of the operation implies no side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and well-structured, but includes a long return shape example that may be redundant given the presence of an output schema (context signal: Has output schema: true). Could be more concise by relying on the output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 parameters and an output schema, the description covers purpose, usage context, behavioral edge case, and return shape. The only gap is the missing documentation for server_version, which slightly reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: only model_id has a description. The description does not mention server_version at all, leaving the agent unclear on what to provide. The description's return shape includes model_id but not server_version, missing an opportunity to clarify this parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'effective control objectives' with a specific additional feature: origin classification (own/cross/inherited). It distinguishes from siblings like 'get_control_objectives' by highlighting the origin tags and the effective model scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this to see what control objectives the model is on the hook for — including those it inherits — before reading coverage or reach,' providing clear context for when to invoke. However, it does not explicitly exclude use cases or mention alternatives, though the context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses auth requirement, None ambiguity, and clear_* flag behavior. However, it omits potential side effects, success return behavior, and idempotency hints. Output schema likely covers return, but description doesn't mention it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise (~8 sentences) and well-structured: purpose first, then constraints, then parameter details. No unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, auth, and main parameters. With output schema present, return values are assumed documented. However, lacks clarity on whether the update is full replace or partial, and no mention of success behavior or rollback.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 83% schema coverage, baseline is 3. Description adds meaning for target_ml (1-5) and csf_tier (1-4) ranges, and the clear_* flags. However, it does not explain the server_version parameter, which lacks description in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Set per-organization level grades for IEC 62443-4-1 and NIST CSF', clearly stating the verb and resource. This uniquely distinguishes it from sibling tools, none of which perform a similar update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states admin-only requirement with a 403 warning, and explains the clear_* flags for resetting values. Lacks reference to alternative tools, but the tool's purpose is distinct enough that no alternative is obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states that member models are not affected and that the operation is limited to tag groups, which is critical safety information for a destructive operation. It does not mention error handling, idempotency, or permission requirements, but the key safety properties are transparently conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences that immediately convey the operation, scope, and caveat about systems. It is front-loaded with the core purpose and avoids redundancy. Every sentence earns its place with actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential behavior—what is deleted and what is preserved—making it adequate for a simple delete operation. However, it omits any explanation of server_version, which is a required parameter, and does not mention error conditions (e.g., what happens if the tag doesn't exist) or idempotency. An output schema exists, so return values are not required, but the parameter gap and lack of error handling leave it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50% (tag_id is described, server_version is not). The description adds no explanation for server_version, its purpose, or its format. The tag_id description in the schema already covers that parameter, so the description contributes nothing beyond what the schema provides. With a missing parameter description and no compensating info, this is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Delete a tag group' with the specific scope that it affects only the grouping, not member models. This distinguishes it from sibling deletion tools like delete_threat_model or delete_reliance, which target different entity types. The resource (tag group) and verb (delete) are explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides important usage context: deletion is supported for TAGS ONLY, and systems have no delete endpoint on this API. This implicitly tells the agent not to use this tool for systems and implies alternative tools (e.g., delete_threat_model) for deleting other entities. However, it does not explicitly name alternatives or state when not to use it beyond the systems limitation, so it stops short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries burden. It discloses that absent fields are treated as unchanged, which is key behavioral info. However, doesn't mention permissions, side effects, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences. First states purpose, second explains usage. No wasted words, front-loaded with key info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given high schema coverage and existence of output schema, description covers the essential behavioral nuance (unchanged fields). Could mention that it updates in-place, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (90%), so description adds marginal value. It explains orthogonal grades concept but doesn't detail each parameter beyond schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Edit a component's properties' using a specific verb and resource. It distinguishes from sibling tools like add_component and remove_component by focusing on modification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on when to set fields ('orthogonal axes', 'set whichever apply') and how to leave fields unchanged ('leave a field unset'). Lacks explicit when-not-to-use, but sufficient for typical edit scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses key behaviors: accepts JSON or free-text, auto-maps to COs, deduplicates, runs as background job (polled for progress), and requires confirmation before saving because it mutates the model. This is comprehensive, though it could mention error handling or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that front-load the core purpose and then detail the key behavioral flow. Every sentence adds value with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, async background job, confirmation step), the description covers the essential aspects: input types, processing flow, and safety confirmation. The output schema exists, so return values don't need explanation. It lacks details on polling mechanism or error handling but is sufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (83%), so the description adds marginal value beyond the schema. It explains that controls_json and free_text are input formats and mentions auto_map mapping behavior, but does not clarify source_label or server_version beyond their schema descriptions. The baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (import), the resource (existing security controls into a threat model), and the method (structured JSON or free-text). It distinguishes itself from sibling tools like get_controls or delete_control by specifying the import functionality with auto-mapping and deduplication.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the async nature and confirmation step but does not explicitly state when to use this tool versus alternatives (e.g., regenerate_controls, add_control). No when-not-to-use or alternative guidance is provided, making it only moderately helpful for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the data returned (fields of each entry) but does not mention any behavioral details such as pagination, ordering, authentication requirements, or side effects. Given it is a read-only list operation, the description is adequate but lacks depth on limitations or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that front-load the core purpose and then add a use case. Every word is necessary, and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (not shown but noted), the description does not need to detail return format. It covers the purpose, context, and key fields. However, it omits prerequisites (e.g., threat model existence, permissions) and does not explain the server_version parameter. For a simple listing tool, it is nearly complete but has minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only model_id has a description; server_version lacks one). The description adds context for model_id by saying 'on a specific threat model' but does not mention server_version at all. With moderate coverage, the description provides some added value but does not fully compensate for the missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all risk acceptances on a specific threat model, defines what risk acceptances are (risks explicitly accepted instead of mitigated), and lists the fields returned (CO id, owner, justification, status, review deadline). This distinguishes it from sibling list tools like list_attestations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a concrete use case: 'Use to inspect which gaps were intentionally accepted versus genuinely unaddressed when triaging at-risk COs.' This gives clear context for when to use the tool, though it does not explicitly mention when not to use it or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description fully handles transparency. Clearly states it's a metadata-only change with no version creation, which is key behavioral information. Lacks permission or reversal details but sufficient for rename.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. Every word adds value, front-loading the action and key constraint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simplicity of tool and presence of output schema, description covers essentials. Could mention what happens after rename (e.g., returned object), but output schema fills that gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% already explaining two of three parameters. Description adds no extra meaning beyond the schema; 'Rename a threat model' doesn't elaborate param usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Rename' and resource 'threat model'. Distinguishes from siblings like delete_threat_model and explicitly notes it's metadata-only, not version creating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides the constraint 'metadata change only, does not create new version' but does not mention when to use vs alternatives (e.g., for other edits) or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides detailed behavioral context: the 'stale' status meaning, automatic re-evaluation triggering, and the meaning of 'misaligned_assertion_ids'. It discloses the default summary-only mode and the option to include full details. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: main purpose first, then detailed breakdown of sufficiency block. It is slightly lengthy but every sentence adds value. Could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the existence of an output schema, the description is complete. It explains the return structure in detail, including per-control fields and the meaning of various statuses. It covers the default behavior and the option to expand details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 83%, so baseline is 3. The description adds value by explaining the sufficiency block structure and the effect of summary_only, which goes beyond the schema descriptions. Other parameters are adequately described in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a verification report with summary stats and sufficiency gaps. It explains the structure of the response, including tier1/tier2 counts and per-control details. This distinguishes it from other report tools among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives or when not to use it. Usage is implied by the tool's purpose, but no exclusions or alternative references are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states 'WITHOUT mutating any state' and 'Read-only,' making side effects clear. It also explains the return shape (plan or refusal) and why refusal happens, but does not fully detail the plan/refusal content or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and not overly long, but it repeats 'Same {plan, refusal} return shape for both event types.' in the second paragraph, which is redundant. Slight trimming would improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides sufficient context for when to use (confirmation flow), what to expect (plan or refusal), and why refusal might occur. It does not include the exact return schema, but that is not required given no output schema is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters have detailed schema descriptions explaining their meaning and allowed values (e.g., event_type lift/split). The tool description adds no extra beyond these schema descriptions, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool previews the inverse plan or refusal without mutating state, and explicitly identifies as a read-only counterpart to undo_composition_event. It distinguishes the purpose (preview vs. apply) with specific language.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by the confirmation flow before committing an undo, and mentions 'read-only counterpart' to guide selection. However, it does not explicitly contrast with other preview tools or state alternatives, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It plainly states the tool only suggests and makes no associations until confirmed, implying read-only behavior. It lacks details like auth requirements, error conditions, or output structure, but the core behavior is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no wasted words. It front-loads the core purpose and quickly adds necessary context about scope and subsequent action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's three parameters and the presence of an output schema (though not shown), the description provides adequate context: purpose, when to use, and relation to a sibling tool. It could mention prerequisites (e.g., model must have functional objectives) but is otherwise sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (2 of 3 parameters have descriptions). The description does not add meaning beyond what the schema already provides for 'model_id' and 'test_ids', and it fails to describe the 'server_version' parameter which lacks schema description. Baseline 3 reduced due to insufficient compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'suggest' and the resource 'which functional objectives each imported test likely covers.' It specifies the scope (unmapped tests) and distinguishes the tool from its sibling 'associate_functional_test' which applies the mappings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this tool for 'unmapped tests (imported without an association, or added without objective ids)' and directs to use 'associate_functional_test' to apply. It provides clear context but does not mention when not to use or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It does disclose that the operation is mutating and adds a meaningful semantic boundary: evidence does not affect control status. However, it omits other behavioral details a fully transparent unannotated mutation tool might include, such as idempotency, duplicate handling, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence states the action and target, and the second adds essential semantic caveats. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderate-complexity mutation tool with an output schema and a well-covered input schema, the description provides the key contextual facts: what it attaches, that it is mutating, and that it does not affect control status. It could mention behavior like replacing vs. appending evidence, but overall it is sufficiently complete for an agent to use it appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%, so the baseline is 3. The description's mention of 'doc, link, or artifact reference' loosely maps to the `type` parameter, but the schema already documents each parameter's meaning and defaults, so the description adds little beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Attach an auxiliary evidence item (doc, link, or artifact reference) to a control.' It clearly scopes what the tool does and distinguishes itself from the sibling tool remove_evidence by framing attachment vs. detachment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when this tool is appropriate and when it is not: evidence is contextual metadata only, does not count toward implementation status, and only assertions prove controls. It also directs users to remove_evidence for detaching an item, giving a clear alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behavioral traits: the platform verifies associations and returns rejected mappings. It implies state mutation but doesn't detail reversibility or permissions. Effective for a partially transparent tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: first states purpose, second gives usage context, third describes outcome. Front-loaded with the core action. No extraneous words. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers inputs, verification behavior, and output (rejected mappings). Output schema exists, so returns are documented. Lacks mention of prerequisites like existence of test/objectives, but is otherwise complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75% (high), so the baseline is 3. The description adds context about verification and rejection but does not elaborate on the parameters beyond what the schema provides. It adds marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('associate') and resource ('functional test with functional objectives'). It distinguishes from sibling tools like 'suggest_functional_test_mappings' by explicitly mentioning using it after or for hand-mapping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies when to use the tool ('after suggest_functional_test_mappings, or to hand-map') and what happens (verification, rejection). It lacks explicit when-not conditions, but provides sufficient usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It discloses that this creates draft edges, runs LLM validation, does not confer credit until separately confirmed, and returns {created, failed}. It does not cover permissions, idempotency, or error details, but the most important state-changing semantics are transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: three sentences, with the primary action front-loaded. The inline code example for selections is terse and helpful, and every sentence contributes meaning without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the lack of annotations, the description covers the key workflow context: relationship to propose_attach_foundation, draft nature, validation, and the absence of credit. It explains the return shape even though an output schema exists. It does not explain server_version or describe failure modes, but for a draft-creation tool this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75% with server_version left undocumented, and the description does not compensate for that gap. It adds contextual meaning for selections (the operator-confirmed subset from propose_attach_foundation) but mostly restates the schema's {source_objective_id, provider_control_id} structure. The model_id and foundation_model_id descriptions in schema are terse and the description adds little beyond them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Create draft delegation edges for selected (objective, control) pairs.' It clearly distinguishes this from the sibling propose_attach_foundation by positioning this tool as acting on the 'operator-confirmed subset' of proposals, and clarifies the draft state and lack of credit until confirmation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful context by noting selections are typically the confirmed subset from propose_attach_foundation and that edges are only drafts requiring later confirmation. It does not explicitly name an alternative tool for confirmation or say when not to use this tool, but the intended workflow is clearly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses important behavioral traits: refusal on partial/mode mismatch, the guarantee of never silently crediting, and the return of the updated edge. It stops short of detailing permissions or side effects beyond the promotion, but the gate behavior is well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, with the first sentence front-loading the primary action and the second providing distinct, crucial behavioral constraints and return information. No filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core action, the validation gate, refusal cases, and the return value. The presence of an output schema reduces the need to describe return structure. Some ambiguity remains regarding accept_partial_as_relied_upon and 'mode mismatch', but overall it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not add information about any of the three parameters. The schema already describes edge_id and accept_partial_as_relied_upon (67% coverage), and the description adds no extra semantics. The baseline of 3 is appropriate given the schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Promote') and identifies the resource ('draft reliance edge') with a clear target state ('active'), which distinguishes it from siblings like create_reliance and delete_reliance. The parenthetical 'credit-soundness gate' adds further specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use (when LLM validation returns 'valid') and when not to use (on 'partial' or mode mismatch). It does not explicitly name alternative tools, but it provides clear contextual guidance for the expected workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It discloses a critical behavioral trait: 'A dismissal is keyed to the divergence's current verdict input hash, so it auto-clears (the row reappears) once the underlying control or objective changes.' It also explicitly states the tool does NOT change the model. The description lacks some details like reversibility or permissions, but the disclosed auto-clearing behavior is significant and beyond the schema/name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the primary action, and every sentence earns its place: purpose, usage condition, key behavioral caveat, and supported row types. There is no irrelevant content or redundancy, and the line break separates the main action from the usage details effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, when to use it, its key behavioral side effect, and the types of divergences it handles. Since an output schema exists, the description need not explain return values. It lacks explicit mention of prerequisites (e.g., how to access reviewed rows) and direct referral to alternatives like accept_coverage_divergences, but for a tool with this complexity, the provided context is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, so the schema already documents most parameters. The description adds that the tool 'Works for coverage AND group_sufficiency rows', which clarifies the 'items' parameter's accepted kinds and reinforces the schema's requirement that control_id is needed for coverage kinds and group_id for group_sufficiency. However, this is marginal beyond the schema, and server_version remains undocumented in both schema and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Dismiss a set of divergences' and clarifies that it does so 'WITHOUT changing the model'. It specifies the scope ('Works for coverage AND group_sufficiency rows') and distinguishes from sibling tools by emphasizing the structural model was right while the LLM was not, which differentiates it from accept_coverage_divergences or other divergence-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool: 'Use for rows you have reviewed and judged not valid.' It also clarifies applicability to both coverage and group_sufficiency rows. However, it does not explicitly mention when not to use it or offer direct alternatives to other divergence tools like accept_coverage_divergences, though the contrast is implied by 'Dismiss' vs 'Accept'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavioral traits. It explicitly states 'Read-only; no side effects' and explains the asynchronous nature of verdict computation, which helps set expectations. It does not cover error conditions or permissions, but for a read tool this is sufficient context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: the first sentence states the purpose and read-only nature, the second explains what it reports and the async behavior. Every sentence adds value without repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a simple getter with an output schema (not shown but present), the description adequately explains what the tool returns (verdict and reasoning) and its async caveat. It also distinguishes from the security-control equivalent. It could mention more about when the verdict is available, but it already covers the key risk of reading 'pending or absent' results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes model_id and functional_test_id well (67% coverage). The description adds minimal parameter-level detail beyond what's in the schema, but it does clarify the relationship between the functional test and its evidence in the context of the verdict. Since server_version lacks a description and the description doesn't compensate for that gap, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads the sufficiency verdict for a functional test, using a specific verb ('Read') and resource ('functional test'). It distinguishes itself from sibling get_sufficiency by noting it covers functional conformance rather than security controls, 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly names the analogous sibling tool get_sufficiency, indicating when to use this tool versus that one. It also notes that the verdict is computed asynchronously, so agents understand the result may be pending or absent, which is valuable usage context. However, it lacks explicit 'when not to use' guidance beyond the sibling distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses read-only nature, includes lifecycle status, and explains the origin field ('own' vs 'inherited') with inherited_from_* context. It also notes that inherited findings are included. Missing details like pagination or ordering, but this is adequate for a list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It front-loads the core action, then adds usage context, then explains the origin semantics. Every sentence carries useful information with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description doesn't need to fully explain return values, but it already covers row contents (lifecycle status, origin) and the own/inherited distinction. It also states read-only. No mention of pagination or limits, but this is a simple listing tool and the description is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers status, model_id, and control_id, but leaves server_version undocumented (75% coverage). The description does not add parameter-specific details; it focuses on output row semantics (origin, lifecycle). Thus it does not compensate for the missing server_version description, though the schema covers most params.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List negative findings recorded on a threat model. Read-only.' This combines a specific verb ('list') with a clear resource ('negative findings' on a threat model), and explicitly labels it read-only, distinguishing it from mutation tools like update_finding and preview_finding_remediation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'use to triage gaps or to find a finding_id for update_finding / preview_finding_remediation.' This names dependent tools and provides clear context. It does not explicitly state when not to use it or offer alternative listing tools, but it gives strong practical guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It states read-only, nothing is created or credited, and returns candidate pairs with match score. This sufficiently discloses behavior for a non-destructive tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero fluff. Clearly states purpose, read-only nature, and next step. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Has output schema, so return details need not be described. Description covers core functionality and next step. Missing minor prerequisites (e.g., model must have objectives) but adequate for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (2 of 3 params have descriptions). The description does not add new parameter meaning beyond the schema. The schema descriptions (consumer model, foundation to delegate to) are clear. Description provides context but not extra semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool proposes which foundation capabilities cover each objective, using specific verbs and resources. It distinguishes from the sibling 'attach_foundation' by noting it is read-only and produces candidate pairs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to feed the chosen subset to 'attach_foundation', indicating it's a precursor. No explicit when-not-to-use or alternatives, but the read-only note suggests appropriate usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains domain semantics but does not disclose side effects, permissions, or success/failure behavior. It implies creation but does not state any constraints or consequences of adding a component.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed but each sentence adds value, explaining the component model, field semantics, and usage distinctions. It is well-structured in paragraphs, though slightly long; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the domain complexity, the description provides necessary context about components, trust boundaries, and internal/external distinctions, and relates to edit_component. It does not cover prerequisites like model existence, but the output schema exists, so return values are not needed. Overall sufficient for an agent to decide when to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 5/6 parameters with descriptions, and the prose adds extra meaning for repo_url (speculative/external) and trust_boundary_ids (comma-separated, drives reach decisions). However, server_version lacks any description in schema or prose, leaving a gap for that required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Add a component to a threat model' and explains what a component represents (maps trust boundaries to code). Distinguishes from siblings like add_asset and edit_component by specifying the component's role and explicitly referencing edit_component for later binding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use add_component versus edit_component, and clarifies the meaning of empty repo_url for external vs internal components. Warns against incorrect binding, giving concrete when-to and when-not-to usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explicitly states 'Read-only; no side effects' and details the output subset. This is strong disclosure, though it does not cover permissions or error conditions, which prevents a perfect 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose, followed by concise behavioral and usage statements. Every sentence earns its place; there is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description need not detail return structure. It covers purpose, behavior, and usage. The only missing context is the significance of server_version and any prerequisites, but this is largely addressed by the required parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50% (model_id described, server_version missing). The tool description does not compensate by explaining server_version or adding deeper meaning to either parameter. This is a notable gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets 'actionable functional gaps' for a model, with a specific verb and resource. It also explicitly distinguishes itself from the sibling tool get_functional_coverage, fulfilling the differentiation criterion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'Use this to decide what to implement or fix next' and names the alternative 'get_functional_coverage' for the full coverage matrix. This gives clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and discloses key behavioral traits: it is mutating, updates the checklist, and rejects unrecognized step_ids without state change. It could add idempotency details or success response, but is strong for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three front-loaded sentences cover purpose, usage, and failure behavior with zero filler. Each sentence earns its place and the structure is logical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The essential context—mutation, usage order, validation—is covered. The output schema exists, so return values need no description, but the unexplained server_version parameter leaves a small gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50% (step_id has a description, server_version does not). The description adds validation context for step_id but ignores server_version, failing to compensate for the uncovered parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Mark one onboarding setup step as done.' It clearly distinguishes itself from siblings by noting it updates the workspace onboarding checklist and is the mutating counterpart to get_setup_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to call after actually performing the setup action and to check current progress with get_setup_status first, naming the alternative. This provides clear when-to-use guidance and an explicit precondition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool is mutating, records the model as a foundation, stores advertised controls, and emphasizes that a capability always advertises a control, never an objective. It stops short of covering permissions or reversibility, but core side effects are transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into three focused paragraphs, each serving a purpose: what the tool does, what a foundation is, and how to structure provides entries. It is slightly longer than strictly needed but every sentence contributes valuable context; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the existence of an output schema, the description covers the core functionality, mutation side effects, provides structure, and relationship to attach tools. However, it omits any semantics for the required 'server_version' parameter, which is also undescribed in the schema, leaving a small but notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 75% of parameters with descriptions. The description adds significant semantics for the 'provides' parameter, including a concrete example and a rule about controls vs objectives. This goes beyond schema-only information and helps correctly construct the array.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb+resource: 'Mark a model as a shared foundation that advertises providable controls.' It clearly distinguishes this from sibling tools like propose_attach_foundation/attach_foundation by stating this tool records the foundation itself, while other models later delegate to it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the tool's role as a prerequisite for delegation, pointing to propose_attach_foundation/attach_foundation as related next steps. It also clarifies what constitutes a foundation and provides input format guidance. However, it does not explicitly state when not to use it or contrast with all alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full transparency burden. It discloses mutating behavior, soft-delete vs permanent erase, the HTTP 409 blocking condition, and the optional audit-trail justification. It does not mention permissions or response format, but the output schema covers the latter. This is solid disclosure for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two punchy sentences: the first states purpose and soft-delete nature; the second explains the blocking condition and gives actionable guidance. No filler, perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a mutating tool with no annotations, the description covers purpose, behavior, conflict conditions, and a prerequisite, while the output schema documents return values. The sibling context and schema round out the picture, making this highly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes model_id, control_id, and reason (with default and 'recorded in audit trail'). The description reinforces the reason parameter and clarifies control_id semantics via the 409 behavior. Since schema coverage is 75% and the description adds some contextual value, the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Soft-delete'), the resource ('a security control'), and the optional justification. It distinguishes from siblings like delete_threat_model and update_control_status by specifying exactly what kind of deletion and the soft-delete semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context: when you want to retire a control without permanent erasure. It also gives a strong usage condition (blocks when control is the only coverage for a CO) and advice to add a replacement control before deleting, which implicitly tells the agent when to reconsider. It stops short of naming explicit alternatives like update_control_status, so not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the multi-step AI pipeline, automatic progress reporting, and the similar-model short-circuit behavior. It does not explicitly state read/write nature, but the context implies a write operation. Still, it is fairly transparent about key behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence summary, then methodology and outputs, then a dedicated section for the similar-model behavior. It is slightly long but front-loaded with the core purpose and avoids unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, output schema, many siblings), the description covers the core functionality and special behavior well. It does not mention prerequisites or error conditions, but the presence of an output schema compensates for missing return-value details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75% (3 of 4 parameters have descriptions). The description adds context for the force parameter by explaining the similarity check bypass but does not significantly enhance the understanding of other parameters beyond the schema. A score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Generate a complete threat model from a feature description.' It specifies the methodology, outputs, and the special similar-model behavior, distinguishing it from sibling tools like refine_threat_model.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: to create a new threat model. It also details the similar-model short-circuit and instructs to either call refine_threat_model or retry with force=True, covering both alternatives and conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral disclosure burden. It explicitly states 'Read-only', which is critical for safety. It also discloses the output structure and the nuanced behavior for composed models (e.g., inherited controls owned by ancestor models, the inherited flag, and the summary count). This goes beyond the schema and provides valuable context about what the tool returns and how it behaves in different model types.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured: the first paragraph delivers the core purpose and usage, and the second handles composed model details. Every sentence adds value—the output fields, the read-only note, the owner_model details, and the summary. It is front-loaded with the most important information. While it could be trimmed slightly, the detail is warranted for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the presence of an output schema (as signaled), the description provides ample context: it explains the meaning of the key outputs (ranked, greedy_plan, summary), the composed model nuances, and the ownership implications. It also includes read-only status and usage intent. This level of completeness ensures an agent can use the tool correctly without needing additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%: model_id is described but server_version has no description. The tool description does not mention either parameter or add any semantics. It focuses entirely on output and usage, failing to compensate for the missing schema documentation. Given the low coverage, the description should have clarified at least the server_version parameter, but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Remediation-leverage plan for a model' and explains the output structure (ranked, greedy_plan, summary). It distinguishes itself from siblings by focusing on prioritization of implementation work, explicitly saying 'Use to prioritize implementation work' and contrasting with fixing objectives one at a time. This differentiates it from other control-related tools like get_controls or get_mitigation_groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: 'Use to prioritize implementation work' and explains the benefit of a single call. It does not explicitly state when not to use it or mention alternative tools, but the use case is well-defined. The absence of exclusions and alternative references keeps it a step below exceptional, but the guidance is unmistakable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although no annotations are provided, the description explicitly states 'Read-only; no side effects.' It also describes the nature of the return: 'Returns every assumption ... with its satisfaction status.' This fully discloses the behavioral contract, compensating for the lack of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with three sentences: purpose, return details, and usage guidance. It is concise but slightly redundant (e.g., 'cross-model dependency graph' repeated as 'cross-model dependency' in the second sentence). Overall, it is efficient and organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided for this tool, so the description must cover the return type. It does state that it returns assumptions with satisfaction status, but it lacks details on error behavior, pagination, or the exact structure of the dependency graph. Given the absence of an output schema, the description is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema includes two parameters: system_id and server_version. Only system_id has a description in the schema; server_version has none. The tool description does not elaborate on either parameter, failing to compensate for the missing server_version description. Thus the parameter semantics are only partially clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get the cross-model dependency graph for a system.' It uses a specific verb and resource, and the phrase 'cross-model dependency graph' distinguishes it from sibling tools like 'link_system_dependency' or 'get_reachability_verdicts'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides usage scenarios: 'Use to see which assumptions are met by other models' controls, find unsatisfied dependencies, or check system-level completeness.' This clearly indicates when to employ this tool, and it even points to the complementary tool for creation ('Create these links with link_system_dependency').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations are provided, the description carries the full burden and explicitly discloses 'Read-only; no side effects.' This adds behavioral transparency beyond the schema. It does not go into further details like pagination or large result sets, but for a simple list operation the disclosure is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with key information front-loaded. Every sentence earns its place: purpose, safety, usage context, and alternative tool reference.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and a straightforward list operation, the description provides sufficient context for the agent to select and invoke the tool. The only notable gap is the undocumented server_version parameter, which slightly reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%: model_id is documented in the schema, but server_version has no description and is required. The tool description does not explain server_version at all, missing an opportunity to compensate for the schema gap. Only model_id's purpose is indirectly implied by 'for a model.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('list') and resource ('capabilities for a model'), clearly defining the tool's purpose. It also differentiates itself from the sibling tool 'get_capability' by noting it enumerates every capability rather than fetching one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use it ('to enumerate a model's capabilities') and provides an alternative ('use get_capability instead' for full detail of a single capability). Also notes read-only nature, giving clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description adds 'Read-only; no side effects' and clarifies that both built-in and custom frameworks are returned. This covers safety and scope adequately for a list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with each earning its place: purpose, behavior/return content, and usage context. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool, this covers purpose, return content, and relationship to sibling tools. The missing parameter explanation and reliance on an output schema (not shown) keep it just short of a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description only vaguely references a 'version guard'. It does not explain the server_version parameter's meaning or accepted values, leaving the agent underinformed about this required input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'List the compliance frameworks available to map controls against' – a specific verb and resource. It also differentiates from siblings by noting typical use before select_compliance_frameworks and import_compliance_framework.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this to discover framework identifiers before select_compliance_frameworks or import_compliance_framework', giving clear when-to-use context and naming alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden. It clearly states the model is not deleted and that system memberships cannot be detached, which are key non-obvious behaviors. It does not mention permissions or response details, but the core side-effect profile is well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence states the core action, and the second adds a critical limitation. Every sentence earns its place without fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter removal operation with an output schema, the description covers the essential semantics: what is removed, what is preserved, and the tag-only constraint. It could add more about server_version or error cases, but the tool is simple enough that the description is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds only marginal parameter context via 'tag group' and 'model', while the schema already provides thin descriptions for tag_id and model_id. server_version remains completely undocumented, and the description does not compensate for this gap or clarify parameter formatting or semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Remove a model from a tag group') and immediately clarifies that the model itself is not deleted. It also clearly distinguishes this from sibling tools like add_model_to_group and delete_group by emphasizing tag-only removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool (removing a model from a tag group) and when not to use it (systems have no remove-member endpoint). It cites the relevant sibling add_model_to_group for context and makes the API limitation unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosure. It clearly labels the tool as 'Mutating,' explains the side effect (CI verifies the claim), and describes the data flow (submits evidence for an existing test). It does not mention failure modes or idempotency, but the provided information is sufficient for understanding the tool's behavior, making it a 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by well-organized clarifications and alternatives. It is longer than strictly necessary but every sentence contributes value, including the comparison to submit_assertions and the pointers to related tools. It could be tightened, but it is not bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (mutating, requires existing test, involves CI), the description provides a complete picture: what it does, what it doesn't do, when to call it, and what to use instead. It also references related tools (get_scan_prompt, get_functional_coverage) for follow-up. An output schema exists, so return values are not needed. Missing error handling details prevent a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, so the baseline is near 3. The description does not directly elaborate on individual parameters beyond what the schema already provides, but it does add high-level context (e.g., 'binds assertions such as "the test exists" and "the test passes"') that helps understand the content of assertions_json. Since it does not compensate for the undocumented server_version parameter, a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Attach machine-verifiable evidence assertions to one already-existing functional test so CI can verify it.' It uses a specific verb (attach) and resource (functional test), and distinguishes itself from sibling tools like submit_assertions, import_functional_tests, and add_functional_test by explaining the differences in scope and behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use the tool ('Call this after the test is implemented') and when not to ('it does not create or register the test'), and provides direct alternatives: 'To bulk-register test DEFINITIONS from your codebase instead, use import_functional_tests; to hand-author a single test use add_functional_test.' Also clearly differentiates from submit_assertions by domain. This is exactly what the guideline dimension looks for.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool mutates state, commits changes, and records justification in the audit trail. It also describes specific error responses, enhancing transparency. However, it does not mention permissions, idempotency, or rate limits, which could be considered gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It begins with a clear one-liner, then explains the workflow and constraints, and ends with error conditions. No unnecessary words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (mutation with workflow dependency and error codes), the description adequately covers the key behavioral aspects: prerequisite call, operator confirmation, and error handling. Since an output schema exists, the lack of output description is acceptable. Minor omissions include missing details on success responses or permissions, but the description is sufficiently complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (two of three parameters have descriptions). The tool description reinforces that `justification` must be non-empty and is recorded, but adds little beyond the schema for `finding_id`. The `server_version` parameter lacks description in both schema and tool description, so no additional meaning is provided. The description provides some value but does not significantly augment the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool applies remediation for a finding and mutates state. It distinguishes itself from the sibling `preview_finding_remediation` by explicitly indicating it commits the changes previewed. The verb 'apply' and resource 'finding remediation' are specific and clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: only after calling `preview_finding_remediation` and obtaining operator confirmation. It also lists error conditions (404, 409, 400, 422) that guide when not to call, and explains the agent's role in getting confirmation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the prose carries the full burden. The description openly states 'Mutating', 'mechanical / non-AI-gated', and 'validate only that every referenced component exists', and it explains the side effect of scoping controls/visible to coding agents. It could have also disclosed irreversibility or permissions, but the behavioral boundaries are reasonably clear and go beyond minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Although the description is longer than a simple phrase, it is tightly structured with a single high-level opening, two alternating bullets for target_type, and a short shared tag about the behavior. Each sentence contributes operational knowledge: what happens to scalars, how repo visibility works, when to use multi-assignment, and what validation applies. There is no repetition of heavy struct/schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For multiple parameters and two semantically different modes with no annotations, the description is almost complete: it covers both target types, the meaning of component scoping, the side effects of empty `component_ids`, the validation guarantee, and important domain specifics. The only notable gap is `server_version` is not described and there is no explicit statement about the required `change_reason` semantic format, but the output schema and rich parameter schema fill in many remainder.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers 83% of the parameters, and the description adds real semantic value on top: it explains what `target_type` chooses, what each `target_id` form should look like (with examples like 'CTRL-03' and 'A1'), and what `component_ids` means semantically. The `server_version` parameter is not described, but the schema burden is otherwise largely filled, so some additional value over the schema is present.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states exactly what the tool does: 'Replace an asset's or a control's component scope.' The description then separates the two variants (`target_type = control` vs `target_type = asset`) with concrete use cases and examples, which clearly distinguishes this tool from sibling tools like `remap_control`, `edit_asset`, or `add_component`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives practical 'when to use' guidance: for controls it explicitly says 'Use when wiring a previously unscoped control... adding a second component... or correcting a wrong assignment'; for assets it explains the value of linking assets to components and gives the multi-instance asset example. It does not explicitly say 'do not use this if you need to modify component definitions or other entity attributes', so it stops just short of full exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well: it states 'Read-only (does not mutate the model); runs as a polled background job and uses LLM reasoning.' This discloses key behavioral traits like mutation safety, async execution, and probabilistic reasoning.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: the first sentence states the core purpose, followed by a focused second paragraph clarifying relationship and usage. Every sentence adds value with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description needn't detail return values. It covers the tools' read-only nature, background execution, LLM reasoning, and comparison to assess_model. The only minor gap is the lack of any parameter explanation, but overall it is quite complete for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes only 'model_id' (50% coverage), while 'server_version' lacks any description. The tool description does not mention parameters at all, so it fails to compensate for the schema gap. The description adds no meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Analyze control coverage and surface control objectives that lack sufficient controls.' It also distinguishes itself from the sibling 'assess_model' by explaining it reasons about under-covered COs, making the purpose specific and unique.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: 'Use this to decide what controls to add; use assess_model to score the current state.' It also frames the tool as complementary to assess_model, giving clear when-to-use and when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: re-validation against catalog, skip logic, force option, return summary fields, and error condition. This gives a complete picture of the tool's operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise, with front-loaded purpose and structured details using dashes. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description already summarizes return fields. It covers prerequisites (CWE enabled), skip logic, grounding, and error cases. Missing minor detail about 'server_version' but overall complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (2 of 3 params described). Description adds meaning for 'force' and 'model_id' but does not clarify 'server_version'. The description compensates partially but leaves a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool classifies a model's control objectives against the CWE catalog. It differentiates from sibling tools like get_cwe_catalog and get_model_cwe_tags by focusing on classification rather than retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides context on when to use (for classification), skipping already tagged objectives unless forced, and a 404 if CWE is not enabled. However, it does not explicitly mention alternatives or exclusions compared to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the edge enters draft, runs LLM semantic validation, and carries no credit until confirmed. This provides important behavioral context, though it could mention idempotency or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise paragraphs with clear front-loading of purpose. Structured as bullet points in text, no redundant sentences. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, modes, scope, lifecycle, and credit semantics. With output schema present, return values are not needed. Could be more complete by discussing failure modes or idempotency, but it's sufficient for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 86% schema coverage, baseline is 3. The description adds value by explaining conditional parameters (`source_objective_id`, `source_control_id`) in the context of modes, clarifying when each is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Declare a cross-model dependency' and explains two modes, distinguishing it from sibling tools like `link_dependency` or `declare_foundation`. The verb 'create' and resource 'reliance' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides detailed guidance on when to use each mode (delegated vs relied_upon) with specific parameter requirements. Mentions workspace-scoping and confirmation via `confirm_reliance`. However, does not explicitly contrast with alternative tools or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It states 'Read-only; no side effects' and indicates the tool returns component and asset bindings, which is valuable safety and outcome context. However, it does not mention error behavior, permissions, or rate limits, leaving room for more transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place: the first states the action, the second confirms safety (read-only), and the third gives when-to-use guidance with a sibling alternative. It is front-loaded and free of filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch tool, the description provides adequate context: purpose, safety, and usage direction. An output schema exists, so return value details are not necessary. The only gap is the unexplained `server_version` parameter, but this is a minor issue given the overall clarity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for `model_id` and `capability_id`, covering 67% of parameters. The description adds meaningful context for `capability_id` by pointing to `list_capabilities` as its source, but it does not clarify the required `server_version` parameter, which remains undocumented in both schema and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get one capability with its component and asset bindings.' It clearly differentiates from the sibling tool `list_capabilities`, which enumerates all capabilities, by emphasizing that this tool fetches a single capability given an ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: 'Use when you already have a capability_id (e.g. from list_capabilities) and need its full detail.' It also names the alternative for enumerating all capabilities (`list_capabilities`), making the choice between these two tools unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explicitly states 'Read-only; no side effects,' which is a key behavioral trait. It also mentions the output includes summaries of member threat models, and explains the system concept. It does not cover error conditions or edge cases, but the read-only disclosure and scope limitations are transparent. Slight deduction for lacking permission/error details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two paragraphs but every sentence adds value: purpose, read-only note, then detailed usage guidance with alternatives and conceptual explanation. No fluff, front-loaded with the essential purpose, and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description doesn't need to describe return values. It covers purpose, usage, and provides conceptual background. It might benefit from mentioning potential errors or the exact content of 'summaries', but overall it is sufficiently complete for a read-only get operation with clear alternatives and parameter discovery guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50% (system_id has a description, but server_version is blank). The description adds meaning to system_id by explaining how to discover IDs ('Discover system IDs with list_groups(kind="system")') and clarifies the system domain. However, it does not provide any semantics for server_version, leaving that parameter vague. Since coverage is low, the description partially compensates but not fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a system group by ID, including summaries of its member threat models.' This specifies the verb, resource, and scope, distinguishing it from similar tools like list_groups by clarifying it fetches one system only. The purpose is unambiguous and not a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use ('single-group fetch is supported for SYSTEMS ONLY') and when not to (tags have no fetch-by-id endpoint), with clear alternatives: 'enumerate tags with list_groups(kind="tag")' and 'list_model_groups'. It also explains how to discover system IDs and add members, giving comprehensive context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description covers behavioral facets: returns grouped view with details, explains three parts (groups, defense_in_depth, unmapped). Implies read-only, but could explicitly state no side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: purpose statement, bulleted return details, use cases. No extraneous content, front-loaded with key info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present, description needn't detail return structure. It explains three logical categories, sufficient given moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 67% coverage; description does not add parameter-level details beyond schema. Baseline 3 since most parameters have descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get the current mitigation group structure for a control objective' with specific resource and verb. Distinguishes from sibling set_mitigation_groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists three use cases: before set_mitigation_groups, when reviewing assessment, when assigning unmapped controls. Provides clear context and timing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full transparency burden. It discloses the presence of soft-deleted(asset/attacker) and tombstone(control objective) markers, instructs how to treat them, and mentions restore_entity. It is a read-only getter, but that is implicit from the name and purpose, so no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately sized but well-structured with a clear first line, a list of returned components, and a bolded, bulleted 'Important' section. Every section adds value, but the redundancy of 'full threat model' and the list could be trimmed slightly. Still, it is efficiently organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (not shown), the description need not detail return format. The description adequately covers the key nuances of soft-deleted and removed entities, which are essential for correct agent interpretation. It is complete for a getter tool in a complex domain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not add semantic detail to parameters beyond what the schema provides. Schema coverage is 75% (server_version undocumented), but the uncovered parameter is likely a system version. The description's focus is on output interpretation, not parameters, so it meets the baseline for a getter with straightforward parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a specific threat model by ID.' with a specific verb and resource, and enumerates the returned components (trust boundaries, assets, attackers, etc.). It differentiates from list_threat_models (which likely returns summaries) and other getters like get_entity by focusing on the full model.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on interpreting soft-deleted and removed entities, with instructions to exclude them from current state and include only for history/restore. It also names restore_entity for restoration. It doesn't explicitly compare to alternatives like get_entity, but the purpose is clear enough to be self-contained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral disclosure burden. It details validation rules (HTTP 400 for non-integer keys), the structure of level_definitions and requirements, and clarifies that the framework becomes selectable on threat models. There are no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening purpose, usage guidance, schema breakdown, and examples. It is slightly lengthy but each section adds necessary detail. The structure is front-loaded and logically organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (importing a nested JSON framework), the description is highly complete. It covers the input schema thoroughly, provides validation details, and includes examples. The presence of an output schema means return values don't need to be described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds substantial semantic value for the 'framework_json' parameter, providing a field-by-field breakdown with examples. However, the 'server_version' parameter is completely undocumented in the description, and the schema only has a 50% coverage. The baseline is 3 due to high coverage on one parameter but none on the other.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Import a custom compliance framework.' It specifies the triggering condition (when built-in frameworks don't cover the customer's program) and distinguishes this from other compliance tools like list_compliance_frameworks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly requires 'PRO tier' and explains when to use this tool ('when your customer's program ... is not covered by Mipiti's 11 built-in frameworks'). It also describes the post-import behavior (selectable like built-in). However, it does not explicitly state when not to use it or mention alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does a good job: it explains the dependency becomes a compliance requirement, describes two independent satisfaction paths, and discloses the unlink sentinel behavior. Minor gaps remain around failure modes or auth needs, but the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-sentence summary, then expands with necessary behavioral details. Every sentence contributes: dependency semantics, satisfaction paths, prerequisites, unlink behavior, and inspection tool. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the operation's complexity and the presence of an output schema, the description covers the essential context: prerequisite state, behavioral effects, unlink semantics, alternate attestation path, and a related inspection tool. It does not explain server_version, but the overall guidance is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, so a baseline of 3 applies. The description adds meaningful semantic value beyond the schema by explaining the unlink behavior of target_model_id ('Pass an empty target_model_id to unlink') and tying the operation to linked_co_ids from add_assumption/edit_assumption. server_version remains unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Link an external assumption to a target model in the same system.' It clearly distinguishes itself from sibling tools like add_assumption and edit_assumption by framing the operation as a cross-model, system-scoped dependency.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context: the assumption must already be linked to control objectives, empty target_model_id unlinks, and get_system_dependencies can inspect the result. It does not explicitly state 'when not to use', but it names related tools and prerequisites well.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explains the origin field ('own' vs 'inherited') and notes that inherited assertions are included, adding useful behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured, and front-loaded with the main purpose. Every sentence adds value, and there is no redundant or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential logic (listing, mutual exclusivity, origin explanation). Given the existence of an output schema (not shown) and 75% schema coverage, it provides sufficient context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75% (three of four params have descriptions). The description adds value by clarifying the mutual exclusivity of control_id and assumption_id and the meaning of the origin field, compensating for the lack of annotation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a clear verb and resource: 'List active assertions for a control or assumption.' It precisely states the function and distinguishes itself from sibling tools like submit_assertions or delete_assertion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to provide exactly one of control_id or assumption_id, which is a key usage guideline. While it doesn't compare extensively with all siblings, it gives clear context for when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explicitly says 'Read-only; no side effects' and explains the behavioral nuance that a model may appear under many tags because tag grouping is overlapping.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core action and safety trait, and every sentence adds value: what is returned, the overlapping nature, and the correct alternatives for systems and tags.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only listing tool, the description covers purpose, behavior, return meaning, and sibling alternatives well. The main completeness gap is the unexplained server_version parameter in an otherwise high-clarity description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description reinforces model_id as 'the model whose groups (tags) to list,' but it never mentions or explains the required server_version parameter. With schema description coverage at 50%, the description needed to compensate for that gap and does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List the groups a given model belongs to.' It also distinguishes itself from sibling list_groups by noting tags are the overlapping grouping kind and that per-model listing is only for tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit alternatives: use list_groups(kind="system") to enumerate systems, inspect system membership via get_group, and use list_groups(kind="tag") for all workspace tags. This clearly frames when to invoke this tool versus the siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It declares read-only behavior, describes the structured diff output, and gives an example for one finding kind. It does not mention permissions or rate limits, but covers key behavioral aspects. Almost complete, missing minor details but not contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It starts with a one-line summary, then provides details on usage, behavior, and error cases. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description need not detail return values. It covers purpose, usage, behavior, and error codes. The only gap is the lack of explanation for the server_version parameter, but overall it provides sufficient context for an AI agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (finding_id described, server_version not). Description adds context about the diff shape depending on finding kind, but does not explain server_version. It partially compensates for missing schema descriptions, but could be more explicit about the server_version purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Preview what the platform would do to remediate a finding.' It specifies the resource (finding), the action (preview), and distinguishes it from the sibling `apply_finding_remediation` by noting it returns a diff without applying changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool: 'Use this BEFORE apply_finding_remediation to show the operator exactly what cleanup will happen, and get explicit confirmation before committing.' Also documents error responses (404, 422) which guide usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description provides extensive behavioral details: it creates a new version, reports progress, prevents silent replacement/dropping of entities, handles semantic rejections via 'semantic_rejections', ensures stable CO IDs, and uses soft-delete via remove_entity. This is excellent transparency for a complex mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with bullet points and sections, making it easy to scan. It is longer than average but every detail serves to clarify critical behavior (preservation, rejection, versioning). Could be trimmed slightly but it's well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (semantic preservation, rejection arrays, versioning, tombstones), the description covers all critical aspects. The presence of an output schema for return values reduces the need to describe them. This is complete enough for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 67% of parameters (model_id, instruction). The description adds context for 'instruction' via example but does not explain server_version. Since schema coverage is moderate, the description provides minimal additional value beyond the schema. Baselines: with >80% coverage, score is 3, but here it's 67% so expect more, but description doesn't add much about params, so 3 is fair.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence clearly states the action ('Refine an existing threat model based on an instruction') and specifies what is refined (assets, attackers, trust boundaries, control objectives). This distinctly separates it from siblings like generate_threat_model or edit_asset, as it's for whole-model refinement via natural language instruction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description communicates when to use this tool (to refine an existing model via instruction) and implicitly contrasts with other tools by describing what it cannot do (e.g., silently replace entities) and referencing remove_entity as the way to delete entities. However, it does not explicitly compare to alternative tools like edit_asset or generate_threat_model, so there's room for explicit differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it excels: it states the operation is non-destructive, changes no assertions/controls/verdict content, causes no ID churn, runs in the background, and covers all verdict kinds. This gives the agent a clear, trustworthy behavioral model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but every sentence adds value: it explains the failure scenario, the effect, the scope, the non-destructive nature, the background execution, and the distinction from recompute_verdicts. It is dense with useful content, though it could be trimmed slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool's behavior, scope, and follow-up recommendations are thoroughly described, and an output schema exists to cover return values. The only notable completeness gap is the ambiguous server_version parameter, but overall the description is nearly sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes model_id, but server_version has no description and the description text does not compensate for it. Schema description coverage is only 50%, and the description adds no parameter-specific guidance, leaving server_version ambiguous and underspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Re-trigger a model's parked verdict re-evals after a transient failure.' It clearly distinguishes this tool from recompute_verdicts, which is its closest sibling and does something materially different.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage criteria: use when a re-eval fails transiently (provider outage, exhausted credits, timeout). It also states when to prefer this over recompute_verdicts and explains why recompute_verdicts is not suitable for un-parking failed jobs. This is model behavior for usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that attestations can mitigate linked COs and that expiration makes COs at-risk. It also mentions manual attestation is rejected for non-applicability assumptions. However, it doesn't mention idempotency, permissions, 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no wasted words. Purpose is front-loaded, usage guideline follows, and behavioral consequence is provided last. Highly efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters and required fields, the description covers main functional aspects including restrictions and downstream effects. It could mention the purpose of the 'statement' parameter or default expiry behavior, but these are covered in the schema. Output schema exists but not needed to evaluate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 86% (high), and the description adds no extra meaning beyond the schema's parameter descriptions. Parameters are already well-documented in the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool records an affirmation for an assumption. It distinguishes between external and non-applicability assumptions, referencing sibling tools submit_assertions and the verification process, which differentiates it from other assumption-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool (only for external assumptions) and when not (non-applicability assumptions require CI verification). Provides clear alternatives (submit assertions + run mipiti-verify) and explains the consequences of attestation expiration.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool is 'Mutating' and 'records a manual status transition,' clarifying it does not perform actual cleanup. However, it omits details on whether status transitions are validated, whether calls are idempotent, or what side effects occur on existing metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: one sentence states the core purpose, and a second provides usage context with alternatives. No wasted words, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's role in a lifecycle and the large sibling set, the description adequately explains when to use it and how it differs from automatic remediation tools. It doesn't detail return values, but an output schema exists, and the description focuses on the core action and context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (86%), and the schema already describes each parameter. The description adds modest context by mapping statuses to lifecycle actions ('acknowledge, remediate, verify, or dismiss'), but it does not add further meaning to server_version, model_id, or finding_id beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Advance a finding through its lifecycle. Mutating: updates the finding's status and metadata.' This identifies the specific verb (advance/update), the resource (finding), and the scope (status and metadata), and distinguishes it from sibling remediation tools by clarifying it records a manual status transition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use to acknowledge, remediate, verify, or dismiss a finding previously recorded by submit_findings / list_findings.' It also provides an exclusion: 'for gaps whose kind has an automatic fix, preview_finding_remediation + apply_finding_remediation perform the actual cleanup instead.' This provides clear when-to-use and when-not-to-use guidance with named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It explicitly states 'Mutating' and explains that linking is non-destructive ('without moving or copying it'), and that membership is overlapping for tags. It also discloses return payload types for each kind. While it doesn't detail error conditions or idempotency, it provides solid context beyond the bare schema. Not a 5 because it could mention potential side effects (e.g., if the model is already a member) or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and readable, with clear bullet points for kind values. It is not overly long, but it does include a note about removal that could be considered extraneous for this tool's core purpose. Still, the note is valuable for context. Slightly verbose but efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (two kinds, linking semantics, and a return payload), the description covers key contextual aspects: prerequisites, non-destructive action, and return types. It doesn't explain the output schema in detail, but that is not required since one exists. It could mention error scenarios or idempotency, but the provided context is sufficient for an agent to use the tool appropriately in most cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, leaving 'server_version' undocumented. The description does not explicitly explain 'server_version' but does clarify the meaning of 'kind' by listing values and their effects, and it clarifies that 'group_id' refers to tag or system ID. It adds semantic value for 'kind' beyond the schema's simple type. However, it misses the opportunity to explain 'server_version' and could be more thorough for the remaining parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Add a threat model to a group as a member,' with a specific verb and resource. It distinguishes from siblings by explicitly contrasting with 'remove_model_from_group' and noting the API limitation for systems, and it differentiates between tag and system kinds.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool: 'Both the group and the model must already exist,' and it explains the semantics of each kind ('tag' vs 'system'). It also gives a clear when-not-to-use: 'member REMOVAL is tag-only' and references the alternative 'remove_model_from_group', which is a sibling. This is explicit and helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden for safety and behavior disclosure. It goes far beyond the basic operation: it discloses the actual LLM gate mechanics, the distinction between new and restored entities, the behavior of 'similar' proposals and fail-closed cases, and the convergence stop conditions. I cannot give a 5 because I don't see explicit disclosure about whether this tool is destructive (e.g., does it permanently create assets?) or requires additional permissions beyond PRO tier, but the level of detail about the conditional paths and gate behavior is substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-structured. It leads with the purpose, then breaks down the phases, then the side-effect details, then the convergence and trigger. Every sentence contributes critical domain behavior or constraints (PRO tier, LLM gate, restore semantics, convergence, and auto-trigger). No filler or repetition. It is appropriately lengthy for a complex tool, and the structure makes it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 phases, LLM gate, multiple response fields, skipped reasons) and its lack of output schema and annotations, the description is remarkably complete. It covers the operation loop, the branching on restore-candidate gates, distinguishing new vs restored, skipped reasons, operator options for interventions, and convergence. It even links to the `add_asset` behavior for consistency. This is fully enriched for an operational with no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (two of three params described), and the description adds no parameter-specific details. But it does mention that the tool operates on a 'framework' and a 'model' (from the IDs), which gives implicit context for those parameters. Since the schema already covers the most important parameters, the description does not need to repeat them, so this is a baseline 3; there is no added coverage above the schema's own coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description precisely states what it does: 'Automatically close compliance gaps for a framework', immediately followed 'Requires PRO tier.' and a detailed three-phase loop that explains the specific actions (auto-map, exclude, suggest/apply). It clearly distinguishes this from sibling tools like auto_map_controls or check_control_gaps by the phased behavior and the 'restore-candidate LLM gate' nuance. This goes beyond a simple verb+resource and provides a rich, differentiated purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes when this tool is triggered ('runs automatically when a framework is selected'), manual re-triggering ('can be re-triggered manually if the model changes'), and the conditions under which it stops (converges automatically). It also implies potential user intervention or a manual alternative (the lifecycle gate nuance). It doesn't explicitly name a specific alternative tool, but it clearly implies the usage context and when to use this versus a manual mapping process, which is sufficient given the role.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses side effects: removal from assumption_groups entries, dropping of empty groups, and control status reversion to not_implemented. It also clarifies that underlying assumptions are not deleted. This is comprehensive behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two paragraphs: the first explains the core action, the second details side effects. No unnecessary words; each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the operation and the presence of an output schema (not shown but mentioned), the description adequately covers inputs, side effects, and outcomes. It provides sufficient context for an agent to understand the tool's impact.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover model_id and assumption_id (2 of 3, 67% coverage), but server_version lacks description. The tool description does not add extra meaning for parameters; it relies on schema. With moderate coverage, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: converting a violated or retired assumption to controls, generating controls for covered COs and retiring the CO linkage. It distinguishes from sibling tools like get_assumption or remove_assumption by specifying the conversion action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Use when an assumption is no longer valid and the system owner needs to implement controls instead,' providing clear guidance on when to use. It does not explicitly state when not to use, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral disclosure burden. It explicitly states the operation is mutating, requires write access, assigns a fresh model_id on every import, avoids collisions, auto-suffixes title collisions, and is non-destructive by never overwriting existing models.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet information-dense: a one-line purpose, a behavioral block covering mutation/safety/idempotency, and a usage sentence. Every sentence contributes meaningful, non-redundant guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating import tool with a nested envelope parameter and no annotations, the description covers the full lifecycle: source envelope, target workspace, permission requirement, idempotency, collision behavior, and non-destructive semantics. The output schema handles return value details, so no further return explanation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, with envelope and workspace_id described in the schema. The description reinforces these by tying envelope to export_report output and workspace_id to target workspace, but server_version remains unexplained in both schema and description. Value added is moderate but incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: "Import a JSON audit archive... into a target workspace" and immediately clarifies it creates a NEW threat model. It clearly distinguishes from sibling import tools (import_controls, import_compliance_framework, import_functional_tests) by tying to export_report's model archive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: "Use to move or clone a model between workspaces or across instances" and specifies the prerequisite round-trip through export_report. It does not explicitly name alternatives or when-not-to-use, but the workflow and mutation implications are evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the mutating nature ('Mutating: records a...') and the side effect ('re-derives that requirement's coverage in the compliance report'). It does not mention permissions or reversibility, but it covers the key behavioral trait for a mapping action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences. First sentence states the purpose and effect, second gives usage guidance, third lists alternatives. No fluff, well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mapping tool with 7 params and an output schema, the description covers the primary use case, side effects, and distinguishes from related tools. Since output schema is present, return values need no explanation. The description is complete for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 86%, so the baseline is 3. The description does not add param-specific semantics beyond schema, but it gives context about the mapping's effect and manual intent, which indirectly supports the 'notes' and 'confidence' params without overriding them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('map one security control to one compliance-framework requirement') and the resource ('control-to-requirement mapping'), and distinguishes from sibling tools by naming auto_map_controls and auto_remediate_compliance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use: 'for a single, deliberate mapping you are asserting by hand', and provides alternatives: 'to let the LLM propose mappings across many requirements at once, use auto_map_controls; to close gaps end-to-end (map + exclude + fill), use auto_remediate_compliance.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. Discloses side effect: superseded assertions, including count in response and history marker. Also explains rejection with per-CO reasoning. Could mention authorization needs or rate limits, but current disclosure is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Highly concise and well-structured: a single sentence for purpose, then bullet-like mode descriptions, then side effect. Every sentence adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity (multiple modes, side effects) and presence of an output schema, description covers all necessary aspects: acceptance/rejection outcomes, per-CO reasoning, and superseded assertions count. Agent can correctly invoke and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema coverage is 83%, description adds meaningful context: explains interaction between description and codebase_findings parameters, and the two modes. This goes beyond the individual parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool refines a control's description with an AI-gated sufficiency check. Describes two distinct modes (direct description, codebase findings) and combined mode. Distinguishes from sibling tools like update_control_status by focusing on description refinement with evaluation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use each mode (description, codebase_findings, or both). Explains that the AI evaluates if mitigation groups satisfy control objectives. Lacks an explicit 'when not to use' statement, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully bears the burden of behavioral disclosure. It explicitly states that writes do not create a new threat-model version and that the value survives soft-delete + revival of the CO. It also explains how to clear the value. These are non-obvious side effects that are crucial for an agent to understand before invoking the tool. No contradictions exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It opens with the primary action, then provides the context of what CAL is, followed by the critical behavioral note about versioning and persistence, and ends with clearing instructions. Each sentence serves a purpose with no redundancy or fluff. It is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (a setter with 4 parameters and an output schema), the description covers all essential aspects: the semantics of CAL, side effects (version independence, soft-delete survival), and clearing. The output schema already handles return values. The description is sufficiently complete for an agent to use the tool correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 75% of parameters (cal, co_id, model_id have descriptions; server_version lacks one). The description adds some semantic depth for cal (explaining the meaning and clearing behavior), but this largely replicates the schema's own description. It provides no additional detail for co_id, model_id, or server_version. Since schema coverage is high, the baseline is 3, and the description adds marginal value beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Set the per-CO ISO/SAE 21434 Cybersecurity Assurance Level (CAL).' It specifies the verb (Set), the resource (control objective), and the attribute (CAL), and it explains what CAL is, distinguishing it from other control-objective operations. This is a specific, unique action compared to sibling tools like update_control_status or refine_control.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context: it explains that CAL is per-CO, lives on the control_objectives side-table, and how to clear it via cal=None. It doesn't explicitly mention alternatives or exclusions, but the context strongly implies when to use this tool. The guidance on clearing is practical and appears sufficient for most use cases, though it lacks explicit comparisons with other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully carries the behavioral burden — and it does so thoroughly. It discloses the version-creation side effect, LLM-gating against re-adds of soft-deleted assets, the three distinct outcomes (including auto-restore un-deleting tombstones and similar-verdict rejection saving nothing), and specific 503/502 error modes with retry instructions. This is exemplary behavioral disclosure for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but every section earns its place: purpose is front-loaded in the opening sentence, outcomes are structurally separated with bold headers and bullets, and the error modes are compressed into a compact list. The density is justified by the tool's genuine complexity (LLM-gated outcomes, restore logic, authoring constraints). It is well-organized and scannable, though not a model of brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex, LLM-gated tool with no annotations and an existing output schema, the description covers everything an agent needs: outcome envelopes (normal create, auto-restore, similar-verdict rejection), error handling with retry guidance, component scoping semantics, caller/backend responsibility split, and the authoring contract for asset quality. The presence of an output schema relieves it from detailing return values, and what it does describe complements rather than duplicates that schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 86%, so the baseline is 3. The description adds real meaning on top: it groups parameters into 'identity-bearing fields (name, description, security_properties, notes)' vs. 'optional component scoping,' and gives component_ids substantive semantics (canonical bridge between trust boundaries and repos, flows boundary context into the reachability graph, multi-instance shape). The authoring contract also enriches the name parameter. However, server_version and security_properties receive no added meaning beyond the schema, capping this at 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Opens with 'Add a new asset to a threat model. Creates a new version.' — a specific verb+resource pair that states the primary action and its versioning side effect. It distinguishes from the sibling edit_asset by explicitly routing post-create factor overrides there, and the caller/backend split clarifies that this tool creates the asset while the backend handles factor decomposition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names edit_asset as the alternative for post-create overrides ('Override any factor post-create via edit_asset with a change_reason'), and the authoring contract provides prescriptive guidance on what constitutes an acceptable asset to add (name the data/resource being protected, not a mechanism). Component scoping guidance ('Multi-component is the right shape for multi-instance assets') also clarifies when to add components. It stops short of an explicit when-not-to-use exclusion list, so 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it delivers extensively. It discloses version creation, LLM-based factor reasoning, quality_warning conditions, the normal/auto-restore/similar-rejection outcome types, and specific 503/502 error causes. This goes well beyond a generic create operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but front-loaded with the core purpose. The authoring contract paragraph is longer than typical, but it earns its place by clarifying the highest-risk parameter. The references to add_asset and error handling are efficient, though a slightly tighter structure would push it to a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the presence of an output schema, the description covers the essential context: operation semantics, behavioral nuances, failure modes, and related tool workflows. The only minor weakness is relying on familiarity with add_asset semantics, but enough information is included to use this tool safely and effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already strong at 83%, but the description adds meaningful semantic guidance. It groups capability, position, archetype, and trust_boundary_ids as 'identity-bearing fields' and, most importantly, explains what capability should express and warns against access-only phrasing. This adds value beyond the raw schema property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action and resource: 'Add a new attacker to a threat model.' It also distinguishes itself from siblings by noting it is the mirror of add_asset and that edits should go through edit_attacker. The purpose is unambiguous and clearly differentiated from the many sibling mutation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly establishes when this tool is appropriate: callers create an attacker and later override factors via edit_attacker. It does not explicitly list exclusion criteria or say 'do not use for X', but the mirror-of-add_asset note and edit_attacker handoff provide practical guidance for choosing between related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It transparently states that this tool does not run or verify tests and that the status is only a claim, with verification occurring later via submit_functional_test_assertions. This is excellent disclosure of behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using two sentences to convey purpose, usage guidance, and behavioral caveats without any fluff or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool that manually adds a test, the description covers its purpose, when to use it, and its non-verification nature. It is complete enough for an agent to decide when and how to invoke it appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not elaborate on parameter meanings. The schema already provides descriptions for most parameters (though server_version lacks one), but the tool description adds no extra context about the parameters themselves, leaving them to the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: to hand-author a single functional test and map it to objectives. It distinguishes itself from generation and import tools, 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.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use this tool versus alternatives: use it for manually adding a test that generation did not produce, and use import for bulk-registering existing tests. This provides clear usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses that the tool is read-only, makes no LLM calls, and performs no mutation, and explains the deterministic evaluation logic. This covers the core behavioral traits, though it omits potential authorization or error details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact—three sentences—and front-loaded with the core purpose. Each sentence contributes: behavior, differentiation, and a usage tip, with no unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (has output schema: true), the description need not detail return values. It covers the tool's purpose, read-only nature, deterministic behavior, and alternative use case. The description is sufficient for a 6-parameter tool with high schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%, so the schema already documents most parameters. The description adds value by explaining the summary_only parameter (returns only counts) and clarifying that statuses like mitigated/at_risk/unassessed map to the evaluation output, aiding the status parameter's use.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Run the deterministic assurance assessment over a threat model') and resource ('threat model'), with a specific verb. It also explicitly differentiates from the sibling tool check_control_gaps, making its unique purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance for deterministic assessment and directs users to check_control_gaps for LLM-based reasoning about control gaps. The read-only note also signals it is appropriate for safe, non-mutating evaluation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well: it discloses the acceptance lifecycle ('active until it expires or is revoked'), the required components (owner, justification, review deadline), and how accepted objectives appear in triage. It omits some side effects like existing acceptances being overwritten, but overall provides strong behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tightly written paragraphs, front-loaded with the action, and every sentence earns its place by contributing purpose, usage, or behavioral detail. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The presence of an output schema covers return values, and the description provides solid usage and lifecycle context for a 6-parameter write operation. It could mention potential errors, idempotency, or permission requirements, but it is largely complete for an AI agent deciding when and how to invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 83%, so the schema already documents most parameters. The description adds meaning by explaining how owner, justification, and review_by collectively define the acceptance's purpose, and clarifies that review_by forces a revisit by the deadline. This goes beyond raw schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Record') and resource ('residual risk on a control objective'), explicitly names itself as the write counterpart to list_risk_acceptances, and clearly contrasts with mitigating risk. This fully distinguishes it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool (deliberate, documented acceptance decision) versus when not to (unaddressed gap), and directly recommends preferring it over leaving risk implicit. It also references the read counterpart, giving clear contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so thoroughly. It discloses destructive and immediate nature, permanent removal, cascading effects on consumer coverage/posture, non-effect on model's own controls, and the return payload. This goes well beyond a basic 'delete' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences front-load the destructive nature and each sentence adds essential context: what is deleted, consequences, prerequisite step, and lack of alternative. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter delete tool, the description covers prerequisites, effects, return format, and alternatives. Even with an output schema present, it adds valuable behavioral context and makes the tool safely invocable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: edge_id is described in the schema and reinforced in the tool description, but server_version is completely undocumented in both schema and description. The description adds no meaning for server_version, leaving a significant gap for a required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the specific verb+resource: deleting a cross-model reliance/delegation edge. It distinguishes itself from siblings like list_reliance, create_reliance, and confirm_reliance by specifying removal semantics, and from other delete/remove tools by naming the exact resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use list_reliance first to find edge_id, and states there is no toggle alternative—deletion is the only removal path. This gives clear when-to-use and sequencing guidance relative to related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool is read-only with no side effects, states an approximate response size (~1-2KB), and details the exact return shape. It also explains the fallback behavior when composition is unavailable (same shape with zeroed counts and flag_enabled: false), which is critical non-error behavior not inferable from annotations (none provided).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear definition, then provides purposeful usage guidance, return shape, and edge-case behavior. Every sentence adds value; the length is justified by the complexity of the returned data structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the presence of an output schema (not shown), the description includes a comprehensive return shape and behavioral details, covering normal operation, unavailability fallback, warning types, and the intended usage sequence relative to sibling tools. It is complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 50% description coverage: model_id is described as 'ID of the threat model,' but server_version has no description. The tool description adds no additional meaning for either parameter and does not explain the role or format of server_version. The detailed return shape does not compensate for the missing parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Composition index for a model — counts, tree metadata, warnings,' which clearly states what the tool does. It further specifies the resource (a threat model) and distinguishes itself from sibling tools by calling itself the cheapest call in the composition surface, meant to be used first.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Use it first to learn whether composition is available for this model... before drilling into sub-resources.' It explains when to use this tool (before detailed composition operations) and what to check (warnings, tree structure, counts), giving clear context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description thoroughly discloses behavioral nuances: soft-deleted entities carry 'deleted: true', speculative components are returned as-is with empty repo_url as valid state, assumptions have an override applied mirroring list_assumptions, and exact pass sets for trust_boundary. This exceeds the schema's information, satisfying the full burden of disclosure for a read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear bullet points for each entity type, but it is somewhat lengthy. Each bullet provides essential edge-case information, so it earns its place, but a more concise summary could have omitted some examples. Still, it is front-loaded with the core purpose and read-only note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (dispatches on five entity types with distinct behaviors), the description is highly complete. It explains return format, soft-delete semantics, and special cases for each type. Even with an output schema present, the description goes beyond to clarify subtle behaviors, making it fully sufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 75% of parameters with descriptions, but the tool description adds significant meaning for entity_type by detailing the dispatch behavior and providing format examples for entity_id (e.g., A-01, T-03). It does not explain server_version, but the schema has no description for it either, and the essential params are well-covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single entity of any core type by ID' with a specific verb and resource, and lists the five entity types explicitly. It distinguishes itself from list-type tools by noting it returns the native record as-is, not wrapped in an array, which differentiates it from list sibling tools like list_effective_entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: when you need a single entity by ID. It does not explicitly name alternatives for when to use list tools, but it implies this by contrasting with list behavior. It doesn't exclude cases like using list_* for bulk retrieval, but the per-type dispatch and native record return make its purpose clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that tags are resolved from platform catalog, not model-authored, explains stale reasons (missing/deprecated/changed), and how to refresh. Also mentions 404 case, providing full behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no waste. First sentence front-loads purpose, subsequent sentences add key behavioral details. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, description provides sufficient context: what the tool does, what inputs it expects (implicitly), and edge cases (stale tags, 404). No obvious gaps for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description does not add meaning to parameters beyond schema. Schema covers 50% (model_id described, server_version not). Description omits server_version explanation, leaving a required parameter without any semantic guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists CWE weakness classifications tagged onto a model's control objectives, specifying the resource and action. It distinguishes from sibling tools like list_model_tags (general tags) and get_cwe_catalog (catalog).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly mentions when to use (to inspect CWE tags), provides conditions like stale tags and recommends re-running classify_model_cwe to refresh. Also notes 404 error if CWE classification is not enabled, setting expectations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explicitly discloses 'Mutating (bulk)' and then details behavioral nuances: the platform verifies associations, returns rejected ones under 'rejected_mappings', and still imports unmapped tests when associations are missing or rejected. This goes well beyond a generic schema and gives the agent an accurate mental model of side effects and outcomes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and safety profile ('Mutating (bulk)'), then flows naturally into usage details, association edge cases, and alternatives. Every sentence contributes distinct, non-redundant information, so no sentence feels wasted despite the description being longer than a one-liner.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the purpose, bulk mutation, association verification, rejection handling, unmapped test behavior, and explicit alternatives. An output schema exists, so omitting return-value details is appropriate. The only noticeable gap is that 'server_version' remains unexplained, and the description does not clarify whether there is any idempotency or duplicate-handling behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema documents 'model_id' and 'tests_json' well, and the description adds meaningful context for 'tests_json' (existing tests, optional objective associations, rejected mappings, unmapped behavior). However, 'server_version' is required but undocumented in both the schema and the description, leaving the agent to guess what value to supply. The description compensates for the main payload but not for the complete parameter set.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Register tests that already exist in your codebase against a model's functional objectives,' which clearly states the verb (register/import), resource (existing tests), and purpose (counting toward functional conformance). It also includes 'Mutating (bulk)' and explicitly contrasts with 'add_functional_test' for single hand-authored tests, distinguishing it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells the agent to scan the repo's test suite and pass existing tests, and it explicitly directs to the alternative 'add_functional_test' for single hand-authored tests. It also points to 'suggest_functional_test_mappings / associate_functional_test' for later association, providing clear when-to-use and when-to-use-alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states 'Read-only; no side effects,' directly addressing safety. It further explains the return structure and semantics (consumer vs. provider edges, blast radius), providing rich behavioral context beyond simple mutation awareness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise: three sentences, each serving a distinct purpose. The first sentence states the core function, the second clarifies safety and output semantics, and the third gives usage context. No filler words or redundant restatements of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's relative simplicity, the presence of an output schema (notifying the agent of return structure), and thorough coverage of safety, semantics, and usage, the description is complete. The only minor omission is server_version semantics, but that falls under parameter semantics rather than overall contextual completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: model_id has a description, but server_version does not. The description fails to compensate for this gap; it does not mention server_version at all, and only implicitly references model_id via 'a model's.' Since the schema does half the work and the description adds no parameter-specific meaning, the low coverage leaves a meaningful gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List a model's cross-model dependency edges, in both directions.' It uses a specific verb ('List'), identifies the resource ('cross-model dependency edges'), and defines the scope ('in both directions'). It distinguishes itself from sibling tools like create_reliance and delete_reliance by focusing on inspection rather than mutation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Use this to inspect existing dependencies before creating or deleting edges (create_reliance / attach_foundation / delete_reliance), or to understand what breaks if this model's controls change.' This names specific alternative/mutation tools and gives concrete scenarios, making when-to-use unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it explicitly states 'Read-only; no side effects' and gives the exact return shape. It also discloses the approximate overhead of include_assessment_summary, adding useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences front-load the purpose, then cover side effects, return format, and use cases without redundancy. Every sentence provides value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, behavior, return shape, and use cases, and an output schema exists. The only notable omission is any explanation of the required server_version parameter, but that is more a schema-level gap than a description completeness failure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%, and the include_assessment_summary parameter has a detailed description in the schema itself. The tool description adds usage context (discover IDs, portfolio overview) but does not clarify the required server_version parameter, leaving a minor gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List saved threat models in the current workspace', using a specific verb and resource that clearly distinguishes it from siblings like list_capabilities or list_tags. It is immediately obvious what the tool does and its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use this to discover model IDs to pass to other tools, or for a portfolio overview.' The include_assessment_summary parameter description further recommends using this tool instead of calling assess_model once per model for aggregate posture queries, providing clear alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: replaces factors and rationale, re-derives composed scores, records audit trail with change_reason, distinguishes from operator overrides, and details partial failure handling with failed_entities list and 503 status.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured and front-loaded with main purpose. Each paragraph adds value, but could be slightly more concise. Still very effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity and presence of an output schema, the description covers return behavior, side effects, and error handling thoroughly. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (2 of 3 params documented). Description adds meaning for change_reason (default and override usage) but does not cover server_version. Baseline 3 with moderate extra context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool re-runs LLM factor judgment on all assets and attackers, and distinguishes it from regenerating the whole model by specifying that regeneration would destroy controls, assertions, and components.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (re-baselining after bug fix or feature change) and when not to use (for deployment-specific adjustments, recommending edit_asset/edit_attacker instead). Also explains soft-fail behavior and error scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains the mechanical nature (non-AI-gated), the validation behavior (rejects invalid IDs), and the persistence of change_reason in version history. However, it does not mention authorization requirements, rate limits, or whether the operation is reversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: three sentences with front-loaded purpose. Every sentence adds value, no fluff or repetition. The structure places the core definition first, then use guidance, then behavioral constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's straightforward purpose (remap CO mappings) and the presence of an output schema, the description covers key aspects: what it does, when to use, validation rules. It could optionally mention return behavior (e.g., success confirmation), but that is likely in the output schema. The description is complete enough for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80% (missing only `server_version` description). The description adds meaning beyond schema: explains co_ids as 'comma-separated list' and 'must include at least one CO', and change_reason as 'min 10 chars' captured in history. The purpose of each parameter is clear in context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Mechanical, non-AI-gated remap of a control's CO mappings.' It immediately differentiates from sibling tools like `refine_control` and `set_mitigation_groups` by specifying distinct characteristics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use `remap_control` when the operator already knows the correct co_ids and just needs to persist the mapping change.' It provides example scenarios (restoring after stale references) and clarifies that no LLM evaluation runs. Also warns about rejected co_ids (nonexistent/tombstoned).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It does so thoroughly: explains non-destructive behavior, that flagged entities are left with warnings rather than deleted, that controls carry forward, that a new model version is saved, that credits may be consumed, and what the returned envelope looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded, beginning with a precise summary of the tool's purpose. Every sentence provides useful information: use cases, non-destructive behavior, versioning, cost implications, and return format. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no annotations, the description covers the key operational context: when to use, side effects, cost behavior, persistence as a new model version, and the response envelope. This is sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%, with server_version completely undescribed and model_id having a schema description. The tool description does not add meaning for either parameter; it only restates the model context already implied by model_id. server_version remains opaque, and no parameter-level guidance is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: re-run quality validation on a threat model's existing assets and attackers. It also distinguishes itself from regenerating the model by emphasizing it is non-destructive and preserves controls, assertions, and components.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool: to apply validation improvements to an already-generated model or clear stale quality warnings without regenerating the whole model. It also warns against regeneration by noting what would be destroyed, giving clear guidance relative to sibling tools like generate_threat_model or refine_threat_model.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does an excellent job: it explicitly states the tool is 'Mutating — persists inverse state across multiple models', describes the re-run of the divergence detector, the 409 refusal with structured refusal block, the success behavior (persists inverse state, emits structured activity events), and the audit chaining via original_event_id. This is rich behavioral context beyond what any schema could provide. The only minor gap is not describing the exact structure of the refusal block or the output schema, but the output schema exists and the description covers the key behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded: the first sentence states the core purpose, the second sentence covers the refusal behavior, and the third covers success behavior. It's dense but not bloated — every sentence adds value. It uses structured terms (409, lift_undone, split_undone, original_event_id) that are precise. It could be slightly more concise by trimming some parenthetical examples, but overall it's efficient and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a mutating undo operation with divergence detection, multi-model persistence, and structured events), the description is remarkably complete. It covers the preconditions (divergence check), the failure mode (409 with refusal block), the success behavior (persists inverse, emits events), and the audit trail (original_event_id chaining). The output schema exists, so return values don't need to be described in the description. The parameter semantics are well-covered in the schema and description. This is a complete picture for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75% (3 of 4 parameters have descriptions). The description adds significant meaning beyond the schema: it explains the event_type parameter in detail (what 'lift' and 'split' do, what the returned models block carries for each), and clarifies that model_id must match the cited event's threat_model_id or the server rejects with 404. The event_id parameter is also explained in the schema, but the description reinforces its dual nature (surrogate id or structured id). The only parameter without a description is server_version, which is likely self-explanatory. The description compensates well for the 25% gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Apply the inverse of a previous composition event' — a specific verb ('apply') and resource ('composition event'). It distinguishes itself from siblings like lift_composition_entity and split_composition_entity by explicitly mentioning 'inverse' and 'undo', and it references the forward events (lift_applied/split_applied) that it reverses. This is a precise, non-tautological statement that differentiates it from the many sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: it explains when to use this tool (to undo a previous composition event) and when it will refuse (when state has 'materially evolved' since the forward event, listing specific conditions like assertions submitted, downstream COs added, entity edited). It also names the alternative tools (lift_composition_entity and split_composition_entity) implicitly by referencing their events, and the sibling list includes preview_undo_composition, which suggests a preview-then-undo workflow. This is strong guidance on when and when-not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It labels the operation 'Mutating' and warns that the call is rejected if prerequisites are not met. It does not detail permissions, idempotency, or side effects on other entities, but for a status change the key behavioral risk (rejection) is clearly disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly written sentences, front-loaded with the main purpose. The first sentence states the action, the second specifies allowed values, and the third provides a critical warning. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the primary behavior, the two status values, and a critical precondition. An output schema exists, so return values need not be explained. However, the required parameter 'server_version' lacks any description (in both schema and description), leaving some ambiguity about its purpose, but this is a minor gap given the overall clarity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80%, so the baseline is 3. The description adds crucial cross-parameter semantics by linking 'status' to the control's assertion_count and explaining the prerequisite relationship, which is not evident from the individual parameter descriptions. It also implies that implementation_notes are secondary to the status change.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Update the implementation status of a security control' – a specific verb, resource, and purpose. It further clarifies the exact statuses ('implemented'/'not_implemented'), distinguishing it from sibling tools like delete_control or refine_control, which perform other operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit preconditions: 'Marking a control "implemented" REQUIRES at least one assertion... check its assertion_count (via get_controls) first and submit assertions with submit_assertions if it is zero, or the call is rejected.' This tells the agent when to use the tool, when to defer, and which sibling tools (get_controls, submit_assertions) are necessary prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure and excels. It reveals that accepting items modifies controls (adds/removes COs), creates a single version per affected control, validates each item independently, and supports partial batch success with an applied/skipped response. This level of detail far exceeds typical descriptions and gives the agent a clear mental model of side effects and edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a clear lead sentence defines the action, followed by concise mechanics of behavior and a practical usage tip. Every sentence contributes new information—no filler, no repetition. The length is appropriate for the tool's complexity, and the key points are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the purpose, usage workflow, parameter behavior, and operational nuances (validation, partial application, versioning). An output schema exists, so detailed return field documentation is unnecessary; the description still mentions the applied/skipped split, which is sufficient. For a batch mutation tool with no annotations, this is a complete and self-sufficient description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents items, model_id, and change_reason (75% coverage). The description adds significant meaning by explaining how the 'kind' field in items dictates ADDs vs REMOVEs, and how the batch results in a version per affected control. It also provides a filtering strategy on p_covers, which enriches the semantics of the 'items' parameter beyond its structural schema definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: accepting a set of coverage divergences as mapping changes in a batch. It explicitly explains that missing_mapping items ADD COs and spurious_mapping items REMOVE them, which distinguishes it from related tools like get_verdict_divergence (read) and dismiss_verdict_divergences (dismiss). The verb 'accept' and resource 'coverage divergences' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit workflow guidance: read rows first with get_verdict_divergence, optionally filter by p_covers, then pass items here. This clearly communicates when to use the tool relative to its reading counterpart. It does not explicitly enumerate exclusions (e.g., when to use dismiss_verdict_divergences instead), but the context is strong enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It discloses that the tool creates a new model version, links assumptions to COs, and details the deterministic computation behavior of exclusion predicates including audit-trail cause.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with paragraphs and front-loads the main purpose. While slightly long, every sentence adds necessary detail, and the structure aids readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the presence of an output schema, the description covers essential aspects: effect on model version, relationship to COs, and detailed exclusion logic. It is complete enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 91% schema coverage, the description adds significant value by explaining the exclusion predicate behavior beyond the schema, such as wildcard defaults and precedence when exclusion_co_ids is non-empty.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds an assumption and creates a new model version. It explains assumptions as security properties outside the trust boundary. This distinguishes it from siblings like edit_assumption or remove_assumption.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: 'Use this to resolve a CO whose composer verdict is indeterminate...' and details the scenario for exclusion predicates. It also explains the optional exclusion parameters and their precedence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden and does well by stating 'Mutating,' describing the return values for each kind, explaining seeding behavior, and noting uniqueness constraints. It does not cover auth requirements, error formats, or idempotency, but the core behavioral differentiation between tag and system is clearly disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose, then uses a compact bullet-like format for kind-specific details. Every sentence earns its place; there is no filler or redundant restating of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter creation tool with no annotations but with an output schema, the description is highly complete: it defines the domain concept, explains both valid kinds, specifies constraints, describes return values, and references the appropriate sibling tool for post-creation member additions. The only minor gap is server_version semantics, but that is a schema-level detail and does not affect overall usability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80%, so the baseline is already moderate, but the description adds significant semantic nuance beyond the schema: it explains that model_ids seeds tags, must be omitted for systems, and that passing members for system raises. It also clarifies that group names are unique per workspace within a kind, going beyond the schema's brief descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Create a group (tag or system), optionally seeding tag members.' It clearly defines what a group is and differentiates the two kinds, while the sibling list shows this is the only creation tool for groups, 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.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use tag vs system creation and gives a hard exclusion rule: for kind='system', model_ids must be omitted or empty and passing members raises. It also names the follow-up tool, add_model_to_group(kind='system', ...), as the alternative for adding members to a system afterwards.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that the operation is mutating and destructive, mentions the record is permanently removed (not soft-deleted), states the impact on sufficiency/verification, clarifies it does not re-run verification, and explains the 'own vs. inherited' constraint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a behavioral overview followed by usage guidance. Every sentence contributes unique value, and the text is front-loaded with the core action and safety warnings.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the tool's purpose, behavioral traits, usage scenarios, and constraints (ownership, inherited assertions, relationship to verification). Since an output schema exists, the omission of return-value details is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80%, so most parameters are already described in the schema. The description adds no significant parameter-specific details beyond the existing schema descriptions; it does imply the mutual exclusivity of control_id and assumption_id but that is already evident from the schema's 'omit if' phrasing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'permanently delete[s] a single assertion from a control or assumption,' using a specific verb and resource. It also distinguishes the action from related tools like submit_assertions and list_assertions by referencing them as alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly specifies when to use the tool ('use to retract a claim that was submitted in error or that get_verification_report flagged as misaligned') and names alternatives for adding ('submit_assertions') and inspecting ('list_assertions'). It also provides an exclusion by noting inherited assertions must be managed on their source model.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It discloses: destructive nature, permanent, cascading effects on related entities (controls, assertions, findings, attestations, tag/reliance memberships), invalidation of reliance edges from other models, and downstream posture impact. It also states the return shape. This is exemplary transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
One paragraph, front-loaded with the critical fact ('Destructive and permanent'), then cascading impacts. Every sentence contributes concrete information: what is deleted, why it matters (posture impact), how to safely proceed, and what to expect in return. Slightly dense but efficiently organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given destructive complexity and no annotations, the description is remarkably complete: it enumerates destroyed entities, downstream effects (reliance edges), safety suggestion, and return shape. The only gap is the undocumented server_version parameter — its role is unclear. Still, for a destructive tool among ~120 siblings, this is above the bar.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers model_id (the primary target) adequately mid-description, but server_version is undocumented in both schema and description. However, given that many MCP delete-style tools have an implicit server_version parameter and the description doesn't mislead, it's a minor gap. The description adds context about what happens to the deleted object's relationships, which helps with model understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Uses a specific verb+object ('Delete a threat model and all associated data') that clearly distinguishes it from the 120+ sibling tools (which include reads like get_threat_model, mutations like rename_threat_model or delete_reliance). The named scope (model + every version/controls/assertions/findings/attestations) sharply separates it from delete_assertion, delete_control, and delete_group. Zero ambiguity about what entity this tool deletes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly warns 'Destructive and permanent — cannot be undone' and instructs to 'Confirm intent before calling.' It gives a concrete safe alternative — use export_report with format='archive' to keep a copy first — and names the exact tool to call. This is textbook usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description fully discloses behavior: 'Read-only; no side effects (polling does not trigger or alter generation)' and explains status semantics including deferred, failed, and elapsed_seconds with actionable guidance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Structured with a clear lead sentence, a trigger paragraph, and an organized status breakdown. Every sentence adds value—no filler, no repetition. The return shape and statuses are explained compactly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the full return shape, all statuses, the inline-build exception, budget/deferred behavior, and failure handling. With an output schema described in text and no annotations, this is complete for a polling tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: model_id has a description, but server_version has none. The description doesn't mention server_version or add parameter-level detail. model_id is implicitly tied to the threat model, but server_version remains ambiguous, so the description adds no meaningful parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Poll the async control-generation status for a threat model' – a specific verb and resource. It clearly distinguishes from siblings by referencing generate_threat_model / refine_threat_model as the initiators and positioning this tool as the polling counterpart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit trigger: 'When generate_threat_model / refine_threat_model return a controls_status other than complete, controls are being authored in the background — poll this until a terminal state, then read the controls.' It also tells when not to poll: '{status: "none"} when controls were built inline'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It discloses read-only behavior, tombstone handling (removed: true) and that verdict is omitted, and that offset/limit are ignored in single mode. It lacks detail on authentication or rate limits, but those are less critical for a read-only tool with an 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear mode sections, bullet points for readability, and every sentence provides useful information. It is concise without being terse, and the use of bold and code formatting aids scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (two modes, 5 parameters), the description covers all essential aspects: mode selection, tombstone behavior, default behavior, and parameter relevance. The presence of an output schema reduces the need to detail return structure, and the description covers the gaps (e.g., what happens to offset/limit in single mode).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80%, and the description adds significant value beyond the schema by explaining the behavior of offset/limit (0 = summary only) and the mode selection based on co_id. It clarifies the default behavior and the ignore rule in single mode, which goes beyond the schema's basic type descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets the control objective matrix or a single control objective, with explicit two-mode behavior. It distinguishes from siblings like assess_model and list_effective_control_objectives by specifying its unique output (verdict, controls mapping).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly describes the two modes and when to use each (co_id set vs omitted), and mentions that offset/limit are ignored in single mode. It also directs users to assess_model for pass/fail scoring, providing a clear alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility, and it delivers: it states "Read-only," gives the full return shape, explains behavior when composition is unavailable (coverage empty, flag_enabled false), and discloses pagination defaults. This goes well beyond what a minimal description would provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized for efficient scanning: a one-line summary, a clarifying paragraph, a literal return-shape block, and a short note on edge-case behavior. Every sentence earns its place; despite its length, it is front-loaded and free of fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex (rollup with inheritance), yet the description covers the key dimensions: return structure, pagination behavior, composition-unavailable fallback, and how it relates to get_verification_report. Output shape is included inline, so the agent has a full picture of what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (80%), so the baseline is 3. The description reinforces pagination defaults and origin filtering, but these details are already present in the schema; no additional semantic meaning for parameters like server_version is offered. It does not meaningfully exceed the schema's documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource-scope phrase: "Effective coverage rollup with credited inheritance." It further clarifies exactly what is returned (per effective CO: covered status, own vs inherited credit, contributing controls) and explicitly distinguishes itself from get_verification_report, making the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool: "This is the surface that drives the composition view's coverage / compliance numbers — it reflects composed (own ⊕ inherited) math, NOT the per-model coverage shown by get_verification_report." This names the alternative and gives a clear exclusion, which is exactly what strong usage guidance looks like.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explicitly discloses 'Read-only; no side effects' and describes what the report returns, covering the key behavioral traits an agent needs to know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the main purpose, followed by a concise list of return contents and a helpful pointer to the alternative. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, safety, output contents, and usage alternative. With an output schema present, it does not need to detail the return type further. The tool is a read-only report, so this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes model_id but leaves server_version undocumented. The description adds no parameter-level guidance, so it does not compensate for the missing schema description of server_version. With 50% schema coverage, this is adequate but not strong.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it 'Get[s] the full functional coverage report for a model' and enumerates specific contents (per-objective state, Capabilities × Conditions matrix, cell accounting). It distinguishes itself from check_functional_gaps by calling this 'the complete picture' and naming the alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use this tool versus the alternative: 'when you only need the actionable subset... use check_functional_gaps instead.' Also states it is read-only with no side effects, giving clear context for safe invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'Read-only; no side effects' which is a behavioral disclosure. Since no annotations are provided, this is valuable. It also explains the return behavior for list vs fetch modes, though it doesn't detail pagination or error cases. The read-only claim is explicit and helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening sentence, a definition paragraph, and a bullet-like list for parameter behavior. It is concise, front-loaded with the main purpose, and every sentence adds value. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (list vs fetch, with a domain-specific concept), the description is complete. It explains the domain concept (functional objective), the parameter behavior, and points to related tools. The output schema exists, so return values are not needed in the description. The description fully covers the tool's usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (model_id and functional_objective_id have descriptions, server_version does not). The description adds meaning by explaining the functional_objective_id behavior in detail (omitted vs id) and defines what a functional objective is, which goes beyond the schema. It compensates for the undocumented server_version by not needing to explain it, but the description does not mention server_version at all, which is a minor gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists a model's functional objectives or fetches one by id, with a specific verb and resource. It distinguishes from siblings by naming get_functional_coverage and check_functional_gaps as alternatives for different needs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to use this tool vs alternatives: for pass/fail coverage use get_functional_coverage, for actionable gaps use check_functional_gaps. Also clarifies the behavior based on functional_objective_id (omitted vs provided), giving clear context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description takes full responsibility. It explicitly declares 'Read-only; no side effects,' describes the AND/OR group semantics, and details return contents including ungrouped tests. This is thorough behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with three concise paragraphs: purpose, semantic explanation, and usage guidance. Every sentence adds value, especially the necessary explanation of AND/OR group logic. Front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read tool with an output schema, the description provides complete context: what it reads, the grouping semantics, return contents, and when to use it. It also connects to sibling tools, making it self-sufficient for an agent to select and invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%, so the baseline is 3. The description does not add significant parameter-level detail beyond the schema; it explains the domain concept of satisfaction groups but not the parameters themselves, though it reinforces the role of functional_objective_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Read the satisfaction-group structure for a functional objective.' It clearly distinguishes from siblings by naming get_control_assumption_groups and get_mitigation_groups as analogs, and explains what the tool returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use before set_functional_satisfaction_groups to see the current structure, or to trace why an objective is / isn't satisfied.' It also names sibling analogs, providing clear contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden; it explicitly says 'Read-only; no side effects,' and discloses important behaviors such as tombstoned CO exclusion, delegation-aware rollup, and row-shape differences across scopes. This is highly transparent about what the caller can expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The one-sentence summary front-loads the core idea, and the three scope bullets are dense—each earns its place by adding distinct usage context. There is no filler or repetition of what the schema already says.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, modest schema detail, and rich scope-specific behavior, this description is remarkably complete. It documents row shape, exclusions, scope semantics, delegation behavior, and covers the necessary context for selecting among the three main use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description greatly expands on the schema's scope/scope_id details by explaining exactly how each scope value changes scope_id's interpretation and what fields/rows appear. server_version still lacks any explanation, which prevents a perfect score, but the coverage of the two non-trivial parameters is strong.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description leads with a specific definition: 'Prioritized Risk View — one row per live Control Objective — at a chosen scope.' It clearly names the resource and action, and the three scope modes establish how this view is a risk-aggregation tool distinct from simple listing or editing tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Each scope branch includes explicit use guidance: 'Use to triage which COs need attention on one model', 'Use for posture queries spanning multiple models', and 'Use for a portfolio/audit-scope posture rollup.' It gives strong when-to-use context, though it doesn't explicitly name sibling alternatives or state when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It explicitly states 'Read-only' and clarifies that no arguments beyond the version header are needed, providing key safety and invocation details. It does not mention potential errors or prerequisites, but for a simple read-only getter this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, with the core purpose front-loaded and no filler. Every sentence adds practical value: what it does, that it's read-only, when to call it, and what parameters it takes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with an output schema, the description fully covers purpose, usage context, parameter semantics, and safety. The output schema handles return values, so no further detail is needed. The guidance to call before setup actions completes the picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has a single required parameter 'server_version' with no description (0% coverage), but the description compensates by explaining that the only argument is the version header, giving the parameter semantic meaning. It does not specify the format or expected value, but the context makes it understandable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get the workspace onboarding checklist with completed and pending steps,' combining a specific verb and resource. It also distinguishes itself from the sibling 'complete_setup_step' by focusing on retrieving status rather than modifying it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to call before suggesting or performing setup actions to avoid repeating completed steps, and points to 'complete_setup_step' as the alternative for marking steps done. This gives clear when-to-use guidance and differentiates from related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden. It states the operation is read-only, clarifies evaluation is server-side with no CI round-trip, and explains the stale-verdict behavior including automatic fresh evaluation. These details give the agent a clear model of what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long and front-loaded with the core definition, then usage guidance, then stale behavior. Every clause serves a purpose: scope definition, return-value summary, evaluation context, and a direct sibling comparison. No wasted language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's singular focus and available output schema, the description sufficiently covers what the tool does, what it returns (status and reasoning), and edge cases (staleness). It even explains the automatic re-evaluation workflow, leaving little ambiguity. The only missing piece would be parameter details, but those are partially in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Two of three parameters (model_id, control_id) are described in the schema, leaving server_version undescribed (67% coverage). The description's mention of 'current assertion set' and 'control description' provides contextual hints but doesn't explicitly explain any parameter's syntax or semantics. Since the schema already covers most parameters and the description adds little specific parameter meaning, a mid-range score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a sufficiency check for a single control, with the purpose 'whether its submitted assertions collectively cover every aspect of the control.' It distinguishes itself from 'get_verification_report' by focusing on a single control. A specific verb and resource make the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs when to use it: 'Use this for a focused check on one control after submitting assertions.' It names the alternative 'get_verification_report' for whole-model rollup and specifies the additional details that tool provides (tier1/tier2 pass/fail counts and drift/misalignment). This is a model of usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral burden. It explicitly states 'Read-only; no side effects' and describes the returned data as a chronological record with actor, timestamp, and status/expiry as recorded, giving clear expectations without contradicting any annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then adds a concise behavioral note, a usage rationale, and clear alternative pointers. Every sentence provides useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with no annotations and an output schema present, the description fully covers purpose, return contents, safety profile, and related tools. It is sufficiently complete for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%, with server_version undocumented. The description adds contextual meaning around assumption_id via 'attestation history' but does not elaborate on parameter syntax or the role of server_version. Baseline 3 is appropriate since the schema covers most parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List an assumption's attestation history.' It clearly distinguishes this from sibling tools like submit_attestation (record) and get_entity (current fields), and the purpose is immediately obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool ('trace why the assumption is currently attested, expired, or never attested') and explicitly points to alternatives: submit_attestation for recording and get_entity for current fields. It also ties usage to diagnosing attestation-dependent coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden. It discloses composition behavior, provenance tracking, return shape, pagination defaults, and the fallback when composition is disabled (empty kinds with flag_enabled: false). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with paragraphs, a bullet list, and a code block for the return shape. It is front-loaded with the main purpose and every sentence adds value, avoiding redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema is included in the description, behavioral details are thorough, and parameter semantics are mostly covered, the description is complete. It covers pagination, composition disabled edge case, and return structure. Error conditions are not mentioned but are typically implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80% (4 of 5 parameters have descriptions). The description adds value by explaining pagination defaults and the effect of omitting the kind parameter, but does not address the undocumented server_version parameter. Overall, it provides useful context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the effective entity set after composition with ancestors, specifying the kinds included (trust boundaries, components, etc.) and provenance. It distinguishes from siblings like list_effective_control_objectives by pairing them as complementary tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool (to get inherited topology) and explicitly pairs it with related tools for coverage credit. However, it does not explicitly state when not to use it or provide direct alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavior. It says 'Read-only; no side effects' and explains the semantics of each kind, including that tags never affect posture or credit while systems drive rollups. It also details the response shapes (e.g., returns tags array vs. items array with id, name, description, model_count). This goes beyond a simple statement and gives the agent a clear mental model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: it opens with a clear one-line purpose, then expands to define terminology and contrast the two kinds, and ends with usage guidance. Each sentence adds value; there is no fluff. Despite its length, it is concise because every detail earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (two kinds with different response shapes), the description is complete. It explains both kinds, their implications, and response formats, and it gives context on when to use the tool. The presence of an output schema further reduces the need to describe return values in prose. It also clarifies common use cases and points to a relevant sibling tool, covering all necessary contextual information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds substantial meaning to the 'kind' parameter by explaining the two valid values, their semantic differences, and expected response shapes. However, it does not add any explanation for the 'server_version' parameter, which is required but lacks a schema description. With 50% schema coverage, the description partially compensates but leaves a gap for server_version, so it is only adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool does: 'List the workspace's groups of a given kind.' It specifies the resource (workspace groups) and the action (list), and further differentiates the two kinds with distinct response shapes. It also distinguishes itself from sibling tool 'list_model_groups' by noting its scope, making it unique and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance on when to use this tool: 'Discover group IDs here before the group risk/compliance/export tools or before adding/removing members.' It also explicitly tells when not to use it and points to an alternative: 'For a single model's tag memberships use list_model_groups.' This is clear and helpful context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description fully discloses behavior: pagination details, the fact that rejected pairs are filtered out of the active queue, that rejected is not paginated, and edge cases when composition is disabled or rejection store is not configured. It also describes the return structure and tier semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with clear sections for each disposition. It is front-loaded with its purpose and uses bullet-like formatting. While every sentence adds value, it could be tightened without losing essential details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all aspects: use cases, two modes, parameter behavior, pagination, edge cases (composition disabled, rejection store not configured), and return structures. It is complete given the tool's complexity and the presence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds substantial meaning to parameters: it explains the disposition values and their implications, that page/page_size are only for active disposition and are ignored for rejected, and describes the structure of candidates and rejections. Schema coverage is 80%, and the description compensates fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states its role as a 'reconciliation triage surface' and explains the pairing of local entities with inherited qualified IDs. It explicitly distinguishes between active and rejected dispositions and references sibling tools like apply_certain_reconciliation_match, providing specific context for its use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It advises using the tool 'on child models in a recursive tree to find duplicates that should be collapsed before they distort coverage.' It also explains when to use each disposition (active vs. rejected) and mentions that certain tier matches are 'safe to auto-apply via apply_certain_reconciliation_match,' but does not explicitly contrast with all alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden, and it does so well by disclosing that the operation is read-only, has no side effects, returns id and name, and takes no functional arguments beyond the version guard. This is comprehensive for a simple listing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each serving a distinct purpose: stating the action, stating the safety and return, and providing context and parameter clarification. No filler or repetition exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema exists), the description covers all necessary aspects: purpose, usage context, safety behavior, return contents, and parameter semantics. It is complete without needing to restate output schema details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema has 0% description coverage for the sole parameter, the description adds meaning by labeling server_version as a 'version guard' and clarifying that no other arguments are needed. This effectively compensates for the schema's lack of detail, though some specifics about the guard's format are omitted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (List) and resource (workspaces), and specifies the scope ('the current user belongs to'). This distinguishes it from sibling list tools like list_threat_models and list_capabilities by clarifying the user-centric scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use the tool: to discover the workspace context, since models, controls, and compliance are scoped to a workspace. However, it does not explicitly mention when not to use it or name alternative tools, so it falls 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and delivers thoroughly. It declares 'Read-only; no side effects (no new version, no mutation)' and explains the AI-based behavior, grounding in 'assets, attackers, control objectives, assumptions, and current security posture,' plus the return shape '{model_id, answer}'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences with a clear structure: purpose, behavior/safety, and usage guidance. Each sentence adds distinct value with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a query tool with no annotations, the description covers purpose, read-only safety, usage alternatives, and return format. The only minor omission is the `server_version` parameter, but this is a system-level constraint and does not affect the tool's core context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 2 of 3 parameters (67%), so the description must compensate but only adds grounding context rather than explicit parameter semantics. It does not clarify the purpose of `server_version`, and the existing schema descriptions for `model_id` and `question` already cover their meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Ask a natural-language question about an existing threat model,' which is a specific verb+resource pair. It further differentiates from siblings by directing users to 'refine_threat_model' for changes and 'get_threat_model / assess_model' for structured data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states 'Use this for interpretation or summary questions' and provides clear exclusions: 'Do NOT use it to change the model — use refine_threat_model for that — and prefer get_threat_model / assess_model when you need structured data.' This gives unambiguous when-to-use and when-not-to-use guidance with named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: it mutates state, is idempotent on the natural key, persists at org scope, and does NOT bump model version. This goes well beyond basic expectations and covers side effects and durability.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with a front-loaded summary, followed by necessary behavioral details. Every sentence contributes meaningful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no annotations, the description fully covers the tool's behavior, including scope, idempotency, and durability. With an output schema present, it doesn't need to explain return values. The relationship to list_reconciliation_candidates is clear, making this a complete description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (80%), so baseline is 3. The description adds value by identifying the natural key (model_id, kind, own_qid, inherited_qid) and explaining that re-rejecting an existing pair returns the same row, which clarifies how parameters relate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Reject a reconciliation candidate' and explains it records a 'these are NOT duplicates' decision. It distinguishes from sibling tools by specifying it's for confirmed non-duplicates and noting idempotency on the natural key.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context: 'Use when list_reconciliation_candidates surfaces a pair that looks like a duplicate but the operator has confirmed it is not.' It implies when not to use (for actual duplicates) but does not explicitly name the alternative tool like apply_certain_reconciliation_match.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It states 'Mutating.' and clarifies the side effect—'does not affect the control's implementation status or any assertions.' This goes beyond the basic action to explain non-impact. However, it doesn't mention error conditions, idempotency, or whether the removal is reversible, which would add completeness. Still, the key mutation behavior and its limited scope are well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: the first sentence states the core action, and the second paragraph provides essential usage and side-effect context in two sentences. No redundant or fluff content. It reads efficiently and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the rich input schema (with descriptions for 3/4 params), and the presence of an output schema (so return values are not needed), the description provides sufficient context. It explains the mutation's limited impact, how to find the index, and refers to related tools (add_evidence, get_controls), making it complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75% (only server_version lacks a description). The description enhances understanding of evidence_index and control_id by explaining how to locate the index—'count its evidence array from 0'—and by specifying the array is zero-based. This adds meaning beyond the schema's default description. It doesn't elaborate on server_version, but the high baseline coverage plus the added context justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states: 'Remove one evidence item from a control by its position in the control's evidence array.' This uses a specific verb (Remove), a specific resource (evidence item from a control), and a precise method (by position). It distinguishes itself from sibling add_evidence and delete_control by focusing on a single evidence item without affecting the control itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance: it explains that evidence is auxiliary metadata and removing it does not affect implementation status or assertions, implying when it's safe to use. It also gives explicit steps to find the index: 'read the control via get_controls (control_id=...) and count its evidence array from 0.' This addresses when and how to use the tool, contrasting with alternatives like add_evidence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral disclosure burden. It states the tool is mutating, runs as a polled background job, returns once complete, replaces ALL assignments, and explains AND/OR/defense-in-depth semantics. This is rich, non-obvious context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and well-structured. It front-loads the purpose, then key behavioral notes, then a concise bullet list for group semantics. Every sentence contributes essential information with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with a background-job execution model and replacement semantics, the description covers all critical aspects: what it does, why it's asynchronous, how to prepare, and what the group semantics mean. An output schema exists, so return-value details are not needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (83%), so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining how groups work (AND within a group, OR across groups) and clarifying defense-in-depth's role, which directly enriches the `groups` and `defense_in_depth` parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Declaratively set the mitigation-group structure for a control objective.' It clearly distinguishes this from sibling tools by emphasizing it replaces ALL assignments and describes the polled background job behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context and a direct prerequisite: 'Call get_mitigation_groups first to see the current structure and the unmapped controls available for assignment.' It explains when to use the tool, but does not explicitly mention alternative tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and excels. It discloses the mutating nature ('persists new assertion records'), states it does not perform verification itself, and clarifies that claims are only recorded for later CI checking. This offers substantial behavioral context beyond typical descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with overview, usage, args, and a comprehensive list of assertion types. It is long due to the tool's complexity, but every section serves a purpose. The front-loading of key information and clear separation of sections make it navigable, though the verbosity is justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a highly complex tool with many assertion types and parameters, this description is nearly complete. It covers purpose, behavior, usage guidance, alternatives, and detailed parameter semantics. The only significant omission is server_version, and since an output schema exists, the lack of return value description is acceptable. Overall, it equips the agent well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It does so thoroughly for most parameters, explaining model_id, control_id/assumption_id usage, and detailing the full structure of assertions_json with all assertion types and their params. However, server_version is a required parameter and is not mentioned anywhere in the description, leaving a notable gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Submit assertions for a security control or an assumption.' It uses a specific verb (submit) and resource (assertions), and distinguishes itself from siblings by explicitly referencing list_assertions and delete_assertion for read/removal operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage guidance including when to use this tool ('does NOT run verification itself—assertions are checked later in CI'), and alternatives ('To read existing assertions use list_assertions; to remove one use delete_assertion'). It also specifies the exact condition of providing one of control_id or assumption_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the disclosure burden. It fully discloses that the tool is mutating and persists new records, and it adds useful context about the finding's meaning and lifecycle. It does not mention potential side effects like duplicates or permissions, but the core mutation semantics are clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a clear opening sentence, a usage context, a conceptual comparison, and a lifecycle note. It is concise yet substantive, with no repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers what the tool does, when to use it, how it relates to sibling tools, and what happens after submission. Since an output schema exists, return values do not need to be described. The only minor gap is server_version, but this is a small omission in an otherwise complete description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents findings_json in detail, and the description adds semantic framing that helps the agent understand how to populate the parameters. However, server_version is undocumented in both the schema and description, and the description does not explain its purpose, preventing a perfect score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Record negative findings ... against the model's controls.' It also explicitly states the mutating nature and distinguishes findings from assertions, making the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit precondition: 'Use after a gap-discovery scan (see get_scan_prompt).' It also clearly contrasts with submit_assertions, explaining that findings are the negative counterpart and that the tool is for when expected control evidence was NOT found.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the full burden and does so well. It states that the tool mutates state, that the pair becomes eligible again on next read, and explicitly notes that model version is NOT bumped — a non-obvious behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-structured, with the core action front-loaded and each sentence adding a distinct piece of information: mutation, effect on queue, when to use, and a notable non-effect. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers purpose, usage, effects, and provenance of the key identifier. Since an output schema exists, omitting return-value details is acceptable. For a state-mutating tool with no annotations, this is a complete and actionable description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents model_id and rejection_id; the description adds useful provenance for rejection_id by pointing to rejections[*].id or the return value of reject_reconciliation_candidate. However, the required server_version parameter remains undocumented in both the schema and description, leaving a coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Remove a persisted reconciliation rejection' — a specific verb and resource that clearly defines the tool's action. It further distinguishes itself from related siblings by explaining it reverses a prior rejection and makes the pair eligible again for the candidate queue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use when the operator changes their mind about a prior rejection.' It also names the source of rejection_id and references both list_reconciliation_candidates and reject_reconciliation_candidate, giving the agent clear context for when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It does so thoroughly: atomic all-or-nothing commit, mapping-only effects preserving status/evidence/assertions, orphan guard evaluated on final state, and rejection of changesets that would leave objectives uncovered. This is transparent about failure conditions and side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized, with the atomicity point front-loaded. It uses three focused paragraphs: definition, usage scenario, and behavioral constraints. Every sentence carries relevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (batch operations, transaction semantics, orphan guard), the description covers the essential aspects. An output schema exists, so return value explanation is not required. Minor omissions like server_version semantics and authorization are secondary; the core behavior is well specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 3 of 4 parameters (75%); server_version is undocumented in both schema and description. The description adds substantial meaning for 'ops' by explaining each operation type and the orphan-guard interaction, and for 'change_reason' by noting it's recorded on version history. However, server_version remains a gap that prevents full compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Apply a batch of control operations atomically as ONE transaction.' It distinguishes itself from the sibling single-operation tools by noting this is for batch reorganization rather than many separate calls, and defines its scope as mapping-only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly directs usage: 'Use this to reorganize a model's controls in a single step' with a deduplication example, and contrasts with 'many separate calls.' It also implies a when-not by clarifying that it only handles mapping operations, not re-authoring descriptions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full disclosure burden — and it delivers richly. It discloses LLM-gating on identity fields, the replace/ambiguous rejection behavior (nothing saved, soft-delete + add-new), server-derived impact composition, quality_warning flagging on contract violations, and specific error codes (503/502/400). This is exemplary transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with a leading summary sentence, markdown headers, and a bulleted outcome list. Every sentence adds substantive information — none is filler. Slightly long but the density of critical behavioral details (gates, outcomes, errors) justifies the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 16 parameters, 3 required, no annotations, the description is remarkably complete: covers accepted/rejected outcomes, the rating-revision audit trail, the soft-delete + add-new workaround, the LLM gate scope, and all error conditions. An agent could invoke this tool correctly without any external documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 94%, which sets the baseline at 3 — the schema already documents most parameters with enums and required-condition notes. The description adds genuine value on top by explaining the relationship between factor fields and the composed impact, and the meaning of change_reason in the operator-override context, which goes beyond the schema's phrasing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
"Edit an existing asset. Only provided fields changed." uses a specific verb+resource with scope qualifier. Clearly distinguishes from sibling add_asset and other edit tools (edit_attacker, edit_threat_model, etc.) by naming the asset resource and the partial-update behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (editing an asset) and when not (editing a soft-deleted asset is rejected — restore_entity first). Names the alternative tool (restore_entity) and references the asset authoring contract via add_asset. Also documents the LLM-gating condition for identity vs factor edits.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden—and it delivers. It explicitly discloses "Read-only; no side effects on the source," return-location differences (content vs. content_b64 vs. envelope), server-side async job behavior with automatic progress reporting, latency caveats for large models, and the signed/verifiable nature of the archive bundle. This is rich behavioral context far beyond what any structured field provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place. It front-loads purpose and safety in the first two sentences, then uses a clean bulleted structure under each scope to organize format behaviors. Details like the archive's full inventory of contents are dense but necessary for correct invocation, and nothing is redundant with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a genuinely complex tool—two scopes, four formats, conditional compatibility, async vs. inline returns—and the description covers every combination's behavior, constraints, return representation, and even the downstream restore workflow. The presence of an output schema means return-value details need not be enumerated, and the description appropriately focuses on the decision logic and side-effect profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description substantially enriches the schema: it explains how scope determines the interpretation of scope_id, maps each format enum value to its exact output representation and sync/async behavior, details the full contents of the archive envelope, and documents constraint interactions between scope and format. The only parameter not addressed is server_version, but 75% schema coverage plus this deep descriptive compensation makes the semantic space well-covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: "Export a threat model or a tag cohort as a downloadable document." It then enumerates the exact scope/format variants, making the tool's function unambiguous and clearly distinct from siblings like import_threat_model_archive (inverse operation) and the report-type getters (get_verification_report, get_compliance_report).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit scope/format compatibility matrix, including direct exclusions: "csv, pdf, and archive are rejected for tag scope" and "archive — Model scope only." It also names the companion tool for restore (import_threat_model_archive). However, it does not explicitly contrast against similar report/document sibling tools (e.g., get_verification_report), so it stops short of full when-not-to-use-this-instead-of-X guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It explicitly reveals a non-obvious side effect: if controls have never been generated, the first list-mode call triggers generation, possibly continuing in the background. It also describes response shapes, 404 behavior in detail mode, default exclusion of orphaned controls, and the orphaned boolean flag. This is thorough and honest for a 'get' tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured with clear mode breakdowns. It is front-loaded with purpose and read-only note, then uses labeled paragraphs (List mode, Detail mode) to organize complex information. Every sentence contributes operational value, and the text avoids fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (two modes, 12 parameters, side effects), the description is remarkably complete. It covers mode selection, parameter applicability, response format, error behavior, versioning, and the orphaned-control concept. The presence of an output schema means return values needn't be explained in detail, and the description wisely focuses on operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is high (92%), the description adds significant meaning beyond individual parameter definitions. It explains that control_id switches between modes, that list-mode filters/pagination/toggles are ignored in detail mode, and that include_orphaned=False defaults to excluding orphaned controls. This cross-parameter behavioral context is not present in the schema and substantially aids correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get implementation controls for a threat model — list or single-control detail.' It specifies the resource (controls), the verb (get), and distinguishes two modes (list vs. detail) with specific triggers (control_id omitted vs. set). This differentiates it from sibling tools like update_control_status or delete_control, which are clearly for mutations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use each mode: 'List mode (control_id omitted)' and 'Detail mode (control_id set).' It also explains which parameters apply to which mode and instructs polling get_control_generation_status if results look incomplete. However, it does not explicitly contrast this tool with alternative retrieval tools (e.g., list_effective_control_objectives), so it lacks explicit 'when-not-to-use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and goes beyond basics: flat derivation is deterministic and not persisted, co_id skips the cross-CO loop, pagination params are ignored in flat mode, and composed mode returns flag_enabled: false with empty verdicts when disabled. It also lists exact reason labels and the conditions producing indeterminate verdicts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long and elaborates each mode, but the front-loaded summary and clear bullet-like structure make it scannable. The remediation guidance and sibling-tool distinction are useful, though the text could be tightened without loss of core information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a 7-parameter tool with two modes and an existing output schema, the description covers all relevant behaviors: the two derivation modes, ignored parameters, return shapes, fallback behavior, and how to address indeterminate verdicts. It sufficiently equips an AI to invoke the tool correctly in both modes and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high, but the description adds meaningful cross-modal semantics: it explains which parameters are ignored in flat mode, the effect of co_id, and the meaning of composed flag. It also maps verdict kinds and reason strings to concrete values such as 'boundary_blocks_vector' and 'attacker_unpositioned', going beyond the schema's per-parameter notes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
'Per-CO reachability verdicts for a model — flat or composed topology' names a specific resource, verb, and mode concept. It clearly distinguishes the flat and composed retrieval cases and differentiates itself from model_coherence_report as the raw-verdict tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use composed=True vs composed=False, when to pass co_id, and when to fall back to flat mode when composition is disabled. It also names model_coherence_report as the alternative for actionable findings and says 'Use this before relying on per-CO reach state for triage, auto-remediation, or audit responses.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden — and it comprehensively delivers. States 'Read-only; no side effects' upfront, details what each kind returns, what's excluded (implemented controls), and how control_id scopes output to one control or all. No contradictions with any 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Approximately 300 words — long but dense for a two-mode tool; front-loaded with purpose and read-only guarantee, with clear '─' section dividers for each kind. Every paragraph earns its place, though minor redundancy exists in repeating kind semantics across sections.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two distinct modes, downstream integrations, and filtering rules, the description fully covers behavior, parameter usage, and follow-up workflow. Output schema exists so return-value explanation would be redundant; nothing material is left unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 75% of params, but the description significantly elevates kind and control_id beyond their schema stubs by explaining semantic differences, defaults, and the ignored-when-functional behavior. model_id and server_version rely on schema alone, which is adequate given their self-explanatory names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with a specific verb+resource ('Get guidance prompts for scanning a codebase') plus an explicit read-only declaration. It distinguishes itself from siblings by enumerating two distinct output kinds (security vs. functional) and exclusions (only NOT_IMPLEMENTED controls), clearly separating it from get_review_queue and get_functional_coverage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Offers explicit when-to-use guidance per kind: 'Use this to drive a gap-discovery pass' for security and 'Drive test implementation from it' for functional. Names four downstream tools (submit_findings, submit_assertions, submit_functional_test_assertions, get_functional_coverage) and clarifies when control_id applies (security only; ignored for functional).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains side effects: mutates state across three models, bumps versions, emits model_refined and lift_applied events, extends visibility to all descendants of the LCA, and includes an over-application gate. It also details conflict resolution behavior and error conditions (400 with missing conflict keys).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, conflict resolution, over-application gate, side effects). It's longer than ideal but every sentence adds meaningful information about behavior, error handling, or related tools. The front-loading of the core purpose is good.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (13 parameters, 8 required, mutation across three models, conflict resolution, over-application gate), the description is remarkably complete. It covers prerequisites, error conditions, side effects, and related operations. The output schema exists, so return values don't need explanation. This is a comprehensive description for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 92%, so the schema already documents most parameters. The description adds value by explaining the semantics of key parameters like acknowledged_third_party_subtrees and skip_overapplication_gate in the context of the over-application gate, and field_resolutions/attached_state_resolutions with the keep_a/keep_b/keep_both values. It doesn't add much for server_version, but that's a minor gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Promote a shared-anchor entity from two sibling descendants to their lowest common ancestor.' It uses a specific verb ('promote') and resource ('shared-anchor entity'), and distinguishes it from siblings like split_composition_entity and undo_composition_event by describing the inverse operation and related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: after the operator has confirmed via the composition lift-candidate view that two entities are the same logical thing. It also explains when not to use it (if new conflicts surface, refresh and resubmit) and mentions alternatives (undo_composition_event, preview_undo_composition, split_composition_entity).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It thoroughly discloses the tool's behavior: replacement semantics, clearing, AI gate with HTTP 422 responses, partial persistence, no force-override, and that assumptions remain in the model. This is exceptional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear bullet points and sections, front-loading the main purpose. While somewhat lengthy, each section adds necessary detail for correct usage. Minor trimming could improve, but it remains effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (AI relevance gate, partial acceptance) and lack of annotations, the description covers all essential aspects: invocation, parameters, success/failure responses, and edge cases. The presence of an output schema (not shown) reduces the burden, but the description is still very complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 80% description coverage; the description adds value by explaining the groups JSON format, the justification length requirement (min 10 chars when non-empty), and the behavior of the groups parameter. It does not explain 'server_version', but overall adds useful semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Declaratively set the assumption group structure for a control.' It explains the AND/OR semantics and how it replaces all assignments. This distinguishes it from siblings like 'set_mitigation_groups' and 'get_control_assumption_groups'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides detailed guidance on when to use the tool, including how to clear groups with an empty object, and explains the AI relevance gate behavior (partial/full acceptance, resubmit strategy). It covers the main usage scenarios comprehensively.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so thoroughly. It discloses mutation, soft-deletion of the duplicate, the server re-validating against live state, returning a 400 on stale candidates, bumping model version, and emitting an activity event. This goes far beyond a simple 'mutates state' warning.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet information-dense. Every sentence contributes: purpose, mutation consequences, usage context, tier-specific behavior, server-side revalidation, and side effects. There is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a complex mutation tool. It covers when to use, what happens, error conditions (400 on stale state), and side effects. An output schema exists, so return value details are handled there. No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (83%), so baseline is 3. The description adds meaningful semantics by explaining how own_qid and inherited_qid map to the duplicate and canonical entities, and clarifies that confirm_heuristic acknowledges structural divergence and is required for heuristic-tier candidates. It does not add much for server_version beyond implicit mention of server re-validation, but overall it adds substantive value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Apply a certain-tier reconciliation candidate. Mutates state.' It clearly distinguishes from sibling tools like list_reconciliation_candidates and reject_reconciliation_candidate by explaining that it applies the candidate and soft-deletes the duplicate entity, making the inherited entity canonical.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool: 'Use after surveying candidates via list_reconciliation_candidates.' It also clarifies the distinction between certain-tier and heuristic-tier candidates, noting that heuristic-tier requires confirm_heuristic=True and is otherwise refused server-side. This provides clear guidance on when this tool is appropriate versus when operator review is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses mutation (writes mappings), PRO tier requirement, background job with typical duration (20-45s), wait-for-completion behavior, and scope limitation. This is exemplary transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured, front-loaded with core purpose, then key constraints and expectations. No redundant filler; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, description needn't detail return values. It covers purpose, usage boundaries, parameters, behavioral nuances, and prerequisites. Completely adequate for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, missing description for server_version. Description adds context on control_id (optional, omit to map all) and clarifies framework/model IDs purpose. It does not compensate for server_version, but the param role might be evident from context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it maps a model's existing controls to a framework's requirements, distinguishing it from manual mapping and full auto-remediation. It also specifies it only creates mappings, never adds or excludes entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly positions between manual map_control_to_requirement and auto_remediate_compliance, with clear differences. Also states when to use (when you want to map existing controls) and implicitly when not (when exclusions/additions are needed).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it excels: it explains the LLM-gating behavior, the server-derived likelihood computation, the quality_warning flag for contract violations, the attestation semantics for trust_boundary_ids, and specific error codes (503, 502, 400). This is rich behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear paragraphs: the core edit behavior, the authoring contract, the likelihood derivation, the LLM gate, and error codes. Every sentence earns its place, and the information is front-loaded with the most important usage details first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (15 parameters, LLM gating, attestation semantics, error handling), the description is remarkably complete. It covers the key behavioral nuances, error conditions, and cross-references to sibling tools. The output schema exists, so return values don't need explanation. This is a model description for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 93%, so the schema already documents most parameters well. The description adds critical semantics beyond the schema: the change_reason requirement context, the attestation behavior of trust_boundary_ids, and the LLM-gate implications for identity fields. It doesn't need to restate every parameter, but it adds meaningful value where it matters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Edit an existing attacker' with a specific verb and resource, and immediately clarifies the partial-update semantics ('Only provided fields changed'). It distinguishes itself from sibling tools like add_attacker and edit_asset by focusing on attacker-specific fields and behaviors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus alternatives: it references add_attacker for the authoring contract, explains when the LLM gate applies (identity-bearing fields) versus when it is skipped (factor and trust_boundary edits), and details the change_reason requirement for factor edits. This is comprehensive usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral disclosure burden. It discloses that only confident rows surface (uncertain middle band is dropped), rows are sorted by confidence so strongest calls come first, each section is paginated with filtered_total, and that group_sufficiency divergences are included. This gives the agent a clear model of the tool's behavior and limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized with clear labels (missing_mapping, spurious_mapping, group_sufficiency), uses bolded terms for key concepts, and front-loads the core purpose. Despite its length, every section adds necessary operational detail—actionability, confidence sorting, pagination, and follow-up tools—so there is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for this complex tool: it covers all divergence kinds, explains their directionality, describes pagination and filtered_total for full review, mentions the related accept/dismiss tools, and notes that group_sufficiency rows are observation-only. The output schema exists and the input schema is well-described, so no additional return-value documentation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents most parameters well, including kind values, limit clamping (1-500), and include_dismissed semantics, so the baseline is 3. The description adds meaningful context beyond the schema by explaining what 'confidence' means via p_covers, how missing_mapping/spurious_mapping translate to add/remove actions, and why pagination matters. This elevates it above the baseline, though server_version and model_id are not elaborated in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific statement of what the tool does: it shows where LLM verdicts disagree with the model's authored state. It then clearly distinguishes the two coverage divergence kinds (missing_mapping and spurious_mapping) and mentions group_sufficiency divergences, making its scope unambiguous and distinct from sibling tools like accept_coverage_divergences and dismiss_verdict_divergences.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool and how to act on its results: confident missing_mapping rows should be accepted to ADD mappings, confident spurious_mapping rows should be accepted to REMOVE mappings, and group_sufficiency rows are observation-only. It also names the related tools (accept_coverage_divergences, dismiss_verdict_divergences) and explains pagination strategy for handling large result sets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden and does so thoroughly: it explains single-CO scoping exclusions, 404 behavior, deterministic composer behavior, that indeterminate verdicts are surfaced as findings rather than LLM-decided, and that external-component unbound findings are permanent markers, not TODOs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Although long, the description is front-loaded with a one-sentence summary and then uses scannable grouped bullets for each finding type with corresponding resolution tool. Every section adds operational value—scoping, finding semantics, remediation routing, and usage conditions—so the length is justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity—12 finding types across multiple concerns—the description is complete: it covers scoping behavior, error semantics, finding structures, entity-ID availability, remediation routing, and relationships to sibling tools. The presence of an output schema reduces the need to specify return formatting in prose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes co_id and model_id (67% coverage); the description adds substantial co_id semantics—which finding families are included, what is excluded in single-CO mode, and the 404 condition. server_version remains undocumented in both schema and description, so this is not a perfect 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific statement: it is a static-analysis report on coherence between component declarations, code-binding strings, and structural reachability of every CO. It clearly distinguishes itself from siblings by naming get_reachability_verdicts as the lower-level alternative and enumerates concrete finding types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use: before relying on component-scoped control discovery, when assertion verification fails for path/repo reasons, or to enumerate structural-completeness gaps. It also tells when to prefer get_reachability_verdicts instead, which is exactly the when-vs-alternative guidance the dimension asks for.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses key behaviors: forces fresh evaluation bypassing quiet-period batching, runs in background, returns specific fields, governor behavior (queued and never dropped), and error mapping (503). It also explains that dry_run does not enqueue and is informational. This is comprehensive and beyond what structured fields could convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with distinct sections for the two modes. It front-loads the main purpose and then details each mode with returns and edge cases. Every sentence adds value, and the format with bullet points enhances readability without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (two modes, background execution, governor, error handling, alternative tool), the description is extremely complete. It covers return values, side effects, edge cases, and references an alternative tool. It also provides enough context for an agent to understand the full lifecycle, making it sufficient even with an output schema present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers dry_run and model_id but lacks description for server_version (67% coverage). The description extensively elaborates on dry_run (modes, returns, informational nature) and adds context for model_id, but does not clarify server_version. Given the coverage is below 80%, the description compensates partially but leaves a gap for one required parameter. Overall, it adds significant meaning beyond the schema for two of three parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: re-run coverage and group-sufficiency verdict evaluation, with an explicit scope (for a model) and an alternative mode (dry-run cost estimate). It distinguishes itself from sibling tools by mentioning retry_verdicts for a specific scenario. Specific verb+resource+scope is present, and the two modes are well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool versus alternatives: it says to use retry_verdicts for unparking stuck verdicts instead of force-enqueueing the whole model. It also explains the two modes (enqueue vs dry-run) and their use cases, making selection clear for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It opens with 'Mutating', explains soft-delete semantics (changed/disappeared controls are soft-deleted and queryable via get_controls(include_deleted=True)), states that unchanged controls keep their metadata, and notes that the tool waits for background job completion. This is thorough and actionable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with a clear purpose statement, followed by behavioral details, scoping rules, and alternative usage. Every sentence adds distinct value; there is no filler or redundant repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex mutating tool with background execution, soft-delete side effects, preservation rules, optional scoping, and an output schema, the description covers all key operational aspects and even references a sibling alternative. It is complete enough for an agent to confidently select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers 80% of parameters with descriptions. The description adds meaningful co_ids semantics by clarifying that only those COs' controls are regenerated and all others are left as-is, and that omitting co_ids rebuilds everything. It doesn't explain server_version, but the high schema coverage reduces the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Regenerate controls from the model's control objectives' and 'Re-authors controls from the current COs.' It also distinguishes itself from the sibling tool remap_control, which is explicitly called out for mechanical mapping fixes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: omit co_ids to rebuild everything, provide co_ids to scope regeneration, and prefer remap_control when only stale/orphaned mappings need fixing. It also explains background job behavior and completion waiting, making when-to-use vs alternatives clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits: it is mutating, creates a new model version, is reversible, preserves entity IDs, and clarifies nothing is hard-destroyed. It also details per-type consequences (tombstoning, orphaning, clearing fields) with precise outcomes, meeting the highest transparency bar.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is partly lengthy but structured with a clear lead sentence, key facts (mutating, reversible, dispatches on entity_type), and organized bullet points for each type. It uses front-loaded information and every sentence adds value—no redundancy. The length is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all critical operational aspects: what the tool does, reversibility, per-type consequences, relationship to edit tools, and that it is not destructive. Given the presence of an output schema for return value details, the description is complete for effective selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes three of four parameters clearly (model_id, entity_id, entity_type), giving 75% coverage. The description adds substantial semantic value to the entity_type parameter by explaining the consequence for each enum value, going beyond the schema. It doesn't address server_version, but that's a minor gap. Overall, it compensates for coverage and adds meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: soft-delete a single entity of any core type, and explicitly distinguishes it from related edit_* tools by explaining when to use removal vs. field changes. It also names the reversible counterpart restore_entity, making the tool's role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool (to remove an entity) and when not to (to change fields, use edit_*). It also highlights reversibility and mentions the alternative restore_entity, giving clear usage context. The per-type consequences further guide when removing might trigger unintended effects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It declares the operation as 'Mutating' and states that it 'Replaces the objective's group structure wholesale,' clearly indicating destructive overwrite. It also explains the AND/OR group semantics and that the structure is applied as-is, providing thorough transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core action and mutation warning. Every sentence provides useful information: the replace behavior, group semantics, ungrouped handling, contrast with sibling tool, and prerequisite read. There is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the operation (wholesale replacement with logical group semantics), the description is remarkably complete. It covers purpose, usage, behavioral implications, and provides an explicit alternative and prerequisite. The existence of an output schema means return values need not be described, so no essential context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema description coverage is high (80%), the description adds significant meaning to parameters beyond the schema. It explains the conceptual semantics of groups_json (AND within groups, OR across groups) and clarifies the purpose of the 'ungrouped' parameter. This exceeds the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb and resource: 'Declaratively set (replace) a functional objective's satisfaction groups.' It also distinguishes itself from the sibling tool set_control_assumption_groups by explicitly noting the absence of an AI relevance gate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: it explains when to use this tool versus set_control_assumption_groups, and instructs the user to 'Read the current state first with get_functional_satisfaction_groups' as a prerequisite. This gives clear guidance on when and how to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behaviors: the ancestor chain construction, inheritance semantics, cycle rejection (HTTP 400), depth limits, version bumping, and return of updated model. This goes far beyond a basic action statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core action. Every sentence adds value: context, usage, edge cases, error handling, and side effects. It is concise without being terse, and organized into logical paragraphs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the absence of annotations, the description covers purpose, usage, behavioral nuance, error conditions, and return value. The presence of an output schema means the described return is sufficient. No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to parent_id by explaining that None clears the parent and that cycles/depth violations are rejected. However, server_version is completely undocumented in the schema and not mentioned in the description, leaving a gap at 67% schema coverage. The parent_id semantics are enhanced, but not all parameters are addressed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Set (or clear) a model's parent on the recursive composition tree.' This clearly distinguishes the tool from siblings like delete_threat_model or rename_threat_model, and the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Use this tool when wiring a child model under a platform / system / shared-services ancestor, or when re-rooting a model after a re-org.' It also explains the clear-parent case with parent_id=None, giving concrete usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and delivers. It details mutations (soft-delete, duplicate state, new local ids), version bumps, activity events (model_refined, split_applied), and audit tracking (split_history). This is rich behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three well-organized paragraphs. The first sentence is a clear action summary; the second adds usage context; the third covers technical route details. Every sentence earns its place, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex mutation tool with no annotations, the description covers purpose, usage, behavioral effects, event emissions, and audit visibility. An output schema exists, so the lack of return-value details is acceptable. This is a thorough and self-sufficient description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (80%), so baseline is 3. The description adds value by clarifying that 'model_id IS the ancestor' and that target_descendants 'each take a copy,' plus explains the creation of new local ids and duplication of attached state. This goes beyond the schema's field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action: 'Push an ancestor-owned entity down to one or more descendants and soft-delete the ancestor's copy.' This clearly identifies the verb, resource, and key side effect. It also distinguishes itself from siblings by explicitly stating it is the 'Inverse of lift_composition_entity.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Use when an entity that currently lives on an ancestor is in fact descendant-specific and should be modeled separately per descendant.' It also names the inverse tool (lift_composition_entity) as an alternative, giving a clear when-to-use vs. when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations provided, so the description carries the full burden of behavioral disclosure. It explicitly states 'Read-only; no side effects' upfront, which is critical for an agent to know this is a safe operation. It also discloses the PRO tier requirement for system/tag scopes: 'System/tag scopes require PRO tier.' Additionally, it warns about the error behavior when invalid parameter combinations are used with tag scope. This level of transparency is excellent given zero annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured for an 8-parameter tool. It front-loads the core purpose and safety profile in the first line, then uses clear section headings ('Filtering / pagination:') and bullet-style formatting for scopes. Each sentence earns its place—scope semantics, filtering rules, pagination rules, and error behavior are all communicated without redundancies. For a tool that is necessarily complex due to its parameter space, this is appropriately concise and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 params, 3 scope types, multiple filters, pagination, scope-dependent behavior, error cases) and the lack of annotations, the description is complete. It covers: what the tool does, output format, scope semantics, filter behavior per scope, pagination behavior, error conditions, prerequisites, tier requirements, and read-only status. The output schema exists, so per-requirement row structure doesn't need to be repeated, but the description still explains the classification categories and coverage counts. No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite the schema having 88% coverage, the description adds substantial additional meaning. It explains how scope and scope_id interact across the three scope types (model, system, tag), clarifying that scope determines how scope_id is read (e.g., 'tag' — 'scope_id' = tag id). It also explains the semantics of level (returns requirements at or below this level, e.g., 1 for L1 only), status (scope-specific applicability), and offset/limit (page-based semantics, with 0 meaning no limit). For each filter, it specifies which scopes honor it. The description also connects framework_id back to the workflow context (use with list_compliance_frameworks), providing workflow-level param context the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific and precise statement: 'Compliance gap-analysis report for one framework at a chosen scope. Read-only...' This clearly identifies the tool's verb (get/report), resource (compliance gap analysis), and the key differentiator (one framework at a chosen scope). It distinguishes itself from siblings like get_review_queue or model_coherence_report by specifying its function. The description also enumerates the classification categories (covered, partial, uncovered, unmapped, excluded) and the output (coverage counts plus per-requirement rows), making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance. It states the prerequisite: 'The framework must first be activated at the same scope via select_compliance_frameworks (with the matching scope), otherwise there is nothing to report on.' It also clearly explains when to use each scope variation and explicitly states what happens when tag scope combines with certain parameters: 'passing status, offset, or limit with scope="tag" raises an error rather than silently returning unfiltered rows.' This is precisely the kind of when-to-use/what-not-to-do information an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: it is mutating, creates a new model version, and only affects soft-deleted entities. It elaborates on side effects per entity type (e.g., reviving COs, un-orphaning controls, restoring trust-boundary reachability, and requiring re-attestation for assumptions). This gives the agent a comprehensive understanding of impacts beyond simple success/failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: it opens with a succinct purpose statement, then uses bullet points for per-type effects. Each line is concise and informative, with no redundant phrases. The length is justified by the complexity of supporting five entity types, and the front-loaded summary ensures quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the existence of an output schema, the description covers all core aspects: purpose, mutation behavior, side effects for each entity type, and prerequisites (soft-deleted state). The per-type details ensure the agent understands domain-specific consequences. The description is complete enough to confidently invoke the tool without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 75% (3/4 parameters have descriptions), the description adds significant meaning to `entity_type` by enumerating valid values and their detailed effects. It also clarifies the condition of soft-deletion for `entity_id`. This goes beyond the minimal schema descriptions and compensates for the undocumented `server_version` by explaining its role implicitly (versioning).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: "Un-soft-delete a single entity of any core type, reversing a prior `remove_entity`." It uses a specific verb (un-soft-delete), specifies the resource (entity of core type), and explicitly links to the inverse tool, distinguishing it from siblings like remove_entity. It also notes it is mutating and creates a new model version.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: "Only affects an entity that is currently soft-deleted." It also states the inverse relationship with `remove_entity`, giving a clear when-to-use scenario. The per-type breakdown further details effects, helping the agent understand when each type is applicable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden and does so thoroughly. It discloses that the tool is mutating, requires PRO tier, replaces the existing framework selection, may trigger background auto-remediation, and propagates tag selections to member models. It also notes that auto-remediate jobs run autonomously and can be re-triggered later.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately structured: a clear one-sentence summary, immediate prerequisite and replacement semantics, then a scoped bullet list. Every sentence adds necessary information, and the format makes the three scope-specific paths easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high complexity of the tool and the absence of annotations, the description is remarkably complete. It covers prerequisites, side effects, scope semantics, replacement behavior, background job execution, and downstream reporting tools. The output schema can handle return-value details, so the description's focus on behavior and context is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description substantially enriches the schema by explaining how scope controls the interpretation of scope_id and detailing the distinct behavior for each enum value. It also adds practical context for framework_ids by directing users to list_compliance_frameworks and import_compliance_framework, going beyond the schema's comma-separated example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action — "Select (activate) compliance frameworks at a chosen scope" — and distinguishes itself from related tools like list_compliance_frameworks, import_compliance_framework, and get_compliance_report. It further clarifies that re-calling replaces the existing selection, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: discover valid ids via list_compliance_frameworks, import custom ones via import_compliance_framework, and view results via get_compliance_report at the same scope. It also explains when to use auto_remediate_compliance later, and describes the different behaviors and side effects for model, system, and tag scopes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Mipiti/mipiti-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server