Threat Modeling MCP Server
OfficialServer Quality Checklist
Latest release: v0.1.0
- Disambiguation4/5
Most tools are cleanly separated by resource type (components, connections, data stores, threats, etc.) with clear CRUD patterns. However, several code-validation tools (validate_security_controls, validate_threat_remediation, validate_threat_model_against_code, execute_code_validation_step) have overlapping purposes and could confuse an agent.
Naming Consistency4/5The naming generally follows a verb_noun pattern (e.g., add_component, list_threats, delete_flow), and batch modifiers are consistent. Deviations exist: some entity types lack a get_* counterpart (components, connections, data stores), and a mix of validate_*, execute_*, and get_* plan/guidance tools introduces minor inconsistency.
Tool Count1/5With 107 tools, this server far exceeds the 50+ threshold for an extreme mismatch. While the domain is broad, the sheer number is overwhelming and suggests the tool surface should be consolidated or broken into smaller servers.
Completeness4/5The server covers the full threat modeling lifecycle: business context, architecture elements, trust boundaries, threat actors, assets, flows, threats, mitigations, code validation, and exports. Minor gaps exist (e.g., no get_component, get_connection, or get_data_store), but they are workable.
Average 3.8/5 across 107 of 107 tools scored. Lowest: 2.8/5.
See the Tool Scores section below for per-tool breakdowns.
- 0 of 1 community issues answered or closed in the last 6 months
- 2 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under Apache 2.0.
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?
With no annotations, the description must fully convey behavioral implications. It only says 'removes a component from a trust zone' and returns a confirmation message, but does not disclose side effects (e.g., whether associated connections or crossing points are affected), failure conditions, or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The first sentence and the second sentence express the same idea redundantly. The Args section duplicates schema information, and the Returns section is minimal. The description would be more concise with a single purpose sentence and no repeated or inferred details.
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 mutating operation with no annotations and sparse behavioral details, the description is incomplete. It lacks information about error handling, prerequisites (e.g., does the component need to exist in the zone?), and any cascade effects, making it insufficient for an agent to fully understand the tool's impact.
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?
Although the schema covers 100% of parameters, the description's Args section repeats the schema and introduces a phantom 'ctx' parameter not present in the schema. This could mislead the agent into thinking ctx is a required input, and it adds no new semantic value 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 states a specific verb and resource: 'Remove a component from a trust zone.' It clearly identifies the action and scope, distinguishing it from sibling tools like add_component_to_zone and update_component.
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 versus alternatives. It does not mention any prerequisites, exclusions, or relation to other component/zone operations, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose destructive implications, but it merely states the clear action without mentioning permanence, unrecoverability, or potential side effects on related entities. It also doesn't clarify whether 'all' is limited to assets and flows or could affect other model parts. This is a significant transparency gap 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but unnecessarily repeats the same statement: 'Clear all assets and flows from the system.' appears twice. This redundancy means one sentence does not earn its place. The structure with Args and Returns is clean, but the duplication prevents a higher score.
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 zero-parameter destructive tool, the description is too sparse. It does not mention whether confirmation is required, how other model data (e.g., assets or flows already linked to threats) is affected, or any way to recover after execution. The presence of an output schema and confirmation message helps, but the description lacks essential safety and scope 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?
The input schema has zero parameters, and the baseline for 0 params is 4. The description adds value by mentioning the 'ctx' argument (for logging and error handling) and the return type (a confirmation message), which are not visible in the schema. This enriches understanding even though there are no formal parameters.
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's action: 'Clear all assets and flows from the system.' This is a specific verb and resource, making the core purpose unambiguous. However, it does not distinguish itself from sibling tools like 'reset_asset_flows' or other 'clear_*' tools, so it misses the top score.
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 gives no guidance on when to use this tool versus alternatives like 'reset_asset_flows' or individual delete tools. It lacks any context about prerequisites, such as whether the user should export data first or whether the tool is intended for starting over. No 'when' or 'when not' information is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/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 that the tool returns a markdown plan and uses AI/AWS validation, but it does not mention side effects, auth needs, rate limits, or what happens if called repeatedly. It also confusingly lists an 'Args: ctx' section while the schema has zero parameters, which could mislead about actual invocation. No contradiction with annotations exists, but transparency is thin.
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 moderately sized but contains redundancy: the first sentence 'Get a comprehensive architecture analysis plan' is repeated in essence by 'This tool returns a detailed plan...'. The Args/Returns structure is clear but the Args section is unnecessary given no schema parameters. The text could be tighter without losing meaning.
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 explains what the tool returns (a markdown plan with prompts for LLM analysis) and mentions the AI/AWS validation aspect, which is useful. But with an output schema present and no annotations, it still lacks guidance on the plan's contents, scope boundaries relative to sibling tools, and when to invoke it. It's adequate but not 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?
There are zero parameters in the schema, which typically earns a baseline 4 since there is nothing to explain. However, the description includes an 'Args: ctx' mention that contradicts the empty input schema, adding unnecessary confusion about tool invocation. Because this is misleading, the score is reduced to 3.
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 returns a comprehensive architecture analysis plan for security concerns using AI-powered analysis with AWS documentation validation. The verb 'get' and resource 'architecture analysis plan' are specific, and the mention of 'system architecture' distinguishes it from sibling plan tools like get_business_context_analysis_plan and get_trust_boundary_analysis_plan. However, it doesn't explicitly name alternatives, so it stops short of a perfect score.
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 the many sibling plan tools. It does not state when to invoke it, what prerequisites exist, or what scenarios call for it. The only implied usage is 'get a plan', but there are no clear context triggers or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the full burden of behavioral disclosure. It notes that the return is 'markdown-formatted', which is useful, but it does not state whether the operation is read-only, what happens if the ID does not exist, or any error-prone aspects. This is a significant gap for a tool with no 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The first two sentences are redundant ('Get details...' and 'This tool retrieves details...'), and the Args/Returns sections duplicate the schema. While the content is not excessively long, the repetition and lack of front-loaded key information reduce efficiency.
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?
This is a simple retrieval tool with an output schema available, so the description need not explain the return format in depth. However, it lacks any mention of error conditions, prerequisites, or usage context. Given the simplicity, it is minimally adequate but leaves room for better guidance on edge cases.
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 100% for the 'id' parameter, and the description repeats the same meaning without adding extra detail. The inclusion of a non-existent 'ctx' argument in the description but not in the schema adds minor confusion, but the schema itself is clear. Baseline 3 applies as the schema already documents the parameter.
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 identifies a specific verb ('Get') and resource ('crossing point'), and the phrase 'specific crossing point' distinguishes it from list_crossing_points or other CRUD operations. However, it does not explicitly contrast with sibling tools, relying on the name and schema for differentiation.
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 versus alternatives. The description does not mention scenarios where retrieval is appropriate, nor any exclusions like 'use list_crossing_points to see all crossings first'. This leaves the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/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 of disclosing behavior. It says it resets to the default set but does not clarify that this likely overwrites or removes existing customizations, whether it is destructive, what 'default set' means, or if the operation is reversible. The tool appears to be a mutation with significant side effects, yet the description omits those details.
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 short but contains redundancy: the first and second sentences say exactly the same thing. The Args and Returns sections are useful but boilerplate. The tool could be improved by removing the repetitive second sentence, making it more concise.
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?
While an output schema exists (so return values are covered) and there are no parameters, the description leaves critical ambiguity: it does not define the 'default set', whether this operation affects only assets and flows or related entities, or how it differs from the sibling 'clear_asset_flows' tool. For a reset operation, this level of detail is insufficient for an agent to understand the consequences.
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 has zero user parameters, so the baseline is 4. The description mentions 'ctx' as an argument, but it is not in the schema and seems to be an internal detail; no user-facing parameter semantics are needed. This does not detract significantly, as there are no parameters to describe.
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 states a specific action ('reset') on a specific resource ('assets and flows') and indicates the result is the 'default set'. However, it repeats the same idea in the second sentence and does not explicitly differentiate from the sibling tool 'clear_asset_flows', though 'reset to default' implies restoring a known state rather than emptying.
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?
There is no guidance on when to use this tool versus alternatives like 'clear_asset_flows' or 'reset_threat_actors'. The description only states what the tool does, not when it should be invoked, prerequisites, or scenarios where another tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must shoulder the transparency burden. It only mentions that a confirmation message is returned, omitting side effects, permissions, validation behavior, or overwrite semantics. Minimal behavioral disclosure for a mutating operation.
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 short and uses a clear Args/Returns layout, but the first two sentences are redundant ('Set the priority' and 'This tool sets the priority'). The extraneous 'ctx' entry also adds noise, reducing overall conciseness.
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 simple setter, the description is too sparse. It lacks any mention of when to use it, how it relates to set_threat_actor_relevance, what happens if the actor doesn't exist, or any validation on the priority range (beyond the schema). The absence of annotations makes this a significant 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?
The schema already fully describes both id and priority (100% coverage). The description repeats these but adds a 'ctx' argument that is not present in the input schema, which could mislead an agent. It contributes no additional meaning for the actual 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 'Set the priority of a threat actor' and adds scope 'in the threat model'. The verb 'set' is specific, and the resource is unambiguous. It distinguishes from the sibling tool set_threat_actor_relevance, which deals with relevance rather than priority.
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 like update_threat_actor or set_threat_actor_relevance. It simply restates the function without any contextual or exclusionary information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It indicates a mutation ('set') and states the return value ('confirmation message'), but does not disclose whether this is an update to an existing record, what side effects occur, or error conditions. For a mutating tool with no annotations, more behavioral detail is needed.
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 structured with Args and Returns sections, but it contains redundancy: the first and second sentences say nearly the same thing. The Args section duplicates schema information, adding length without additional value.
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 tool is simple, and the description includes the return value and parameter intent. However, it lacks usage context relative to sibling threat-actor tools (e.g., why a dedicated 'relevance' setter vs update_threat_actor) and does not cover prerequisites or edge cases. The output schema is mentioned as existing, which helps.
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 100%, so the baseline is 3. The description repeats the parameter descriptions from the schema without adding new information. It also mentions 'ctx' which is not in the input schema, potentially adding noise.
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's function with a specific verb ('Set') and resource ('relevance of a threat actor'), distinguishing it from sibling set_threat_actor_priority. It repeats the purpose in the second sentence, which is slightly redundant but not confusing.
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 compared to related tools like update_threat_actor or set_threat_actor_priority. It does not mention prerequisites (e.g., the threat actor must already exist) or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the burden of disclosing side effects. It only states that the tool advances to the next phase and returns a message and guidance. It does not mention whether the action is reversible, whether it validates completion of the current phase, or what happens at the final phase. This is insufficient for a state-changing tool.
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 first two sentences are near-identical ('Advance to the next phase...' and 'This tool advances to the next phase...'), showing clear redundancy. The Args/Returns structure is logical, but the duplication wastes words.
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 in a phased workflow, the description lacks context about the phase progression, prerequisites, or how it fits with siblings like follow_threat_modeling_plan or get_current_phase_status. The output schema covers return values, but the description fails to provide sufficient usage context for correct invocation.
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 has zero parameters, so the baseline is 4. However, the description lists an 'Args: ctx' entry despite the schema having no properties, which could mislead an agent into thinking there is a parameter. Since there are no actual parameters to explain, the description adds no meaningful semantic value and the misleading note reduces the 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 clearly states the action ('Advance to the next phase') and the resource ('threat modeling process'), making it distinct from sibling tools like get_current_phase_status or follow_threat_modeling_plan. The repetition in the second sentence is redundant but does not obscure the purpose.
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 gives no guidance on when to use this tool versus alternatives, nor does it mention prerequisites, such as completing the current phase or checking current status. There are no exclusions or alternative tool references, leaving the agent to infer usage purely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'clears all threat actors' implies removal, it does not explicitly state that the action is destructive, irreversible, or has side effects. There is no mention of permission requirements or impact on related entities.
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 short but contains redundancy: 'Clear all threat actors.' is immediately restated as 'This tool clears all threat actors from the threat model.' The Args section for a tool with no schema parameters adds minimal value. It could be more concise.
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?
For a simple tool with no parameters and an output schema (though not shown), the description covers the main action and return value. However, it omits critical context such as destructive nature and how it differs from reset_threat_actors, leaving gaps in overall completeness.
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 tool has zero parameters, which earns a baseline of 4 per the rubric. The description mentions 'ctx' in an Args section, but this is likely implementation detail rather than a user-facing schema parameter. No additional parameter semantics are needed.
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 verb 'clear' and the resource 'all threat actors', making the primary purpose obvious. However, it does not distinguish itself from the sibling tool reset_threat_actors, which may perform a similar bulk operation, so it loses a point for lack of differentiation.
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 such as delete_threat_actor (single) or reset_threat_actors. It does not mention context, prerequisites, or scenarios where one should choose this over sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for disclosing behavior. It mentions the return format (markdown-formatted list) and a ctx argument for logging/error handling, but does not explicitly state that the tool is read-only, safe to call anytime, or free of side effects. The read-only nature is only implied by the 'get' prefix.
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 brief and structured with clear sections for Args and Returns. It front-loads the primary purpose. Minor redundancy exists between the first line and the second sentence ('Get all...' vs 'returns all available...'), but overall it is concise and easy to scan.
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 tool is simple, has an output schema, and the description explains the return type. However, it does not clarify whether the business context must be set before calling, nor does it explain what 'features' means in this context. The misleading ctx parameter also reduces completeness. For a basic metadata getter, it is adequate but not fully comprehensive.
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 zero properties, but the description lists an 'Args: ctx' parameter. This introduces an undocumented parameter that is not present in the schema, potentially misleading the agent into thinking it must supply ctx. This is confusing and detracts from parameter clarity, even though the schema itself is 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's purpose: 'Get all business context features with descriptions.' It uses a specific verb ('get') and resource ('business context features'), and distinguishes itself from siblings like get_business_context by focusing on features/metadata rather than the actual context values.
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 explicit guidance on when to use this tool versus alternatives like get_business_context or set_business_context. Usage is only implied by the tool name and purpose; there is no mention of exclusions or prerequisites, leaving the agent without clear decision-making context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It describes the action as 'Get' and 'provides information', which implies a read-only operation, but it does not explicitly disclose side effects, permissions, error handling, or any limitations. Since an output schema exists, the return value description is redundant, and no additional behavioral traits are disclosed beyond what the name implies.
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 concise with two sentences and separate Args/Returns sections. It is front-loaded with the purpose. However, the Args section is unnecessary since the schema has no properties and might cause confusion about a 'ctx' parameter that isn't in the schema. This prevents a perfect score, but overall it is efficiently written.
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?
This is a simple getter with no parameters, and an output schema exists, so return values are covered. However, the description lacks usage guidance and behavioral transparency, and it does not differentiate from a similar sibling tool. Given the tool's simplicity, the description is adequate but has clear gaps in contextual completeness.
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 has zero parameters, and the baseline for 0 params is 4. The description mentions an 'Args: ctx' section, which is not present in the schema, but this is likely a standard MCP context argument that is not user-supplied. The description does not add much beyond the schema since there are no parameters to explain, but it does not detract significantly.
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's function: getting the current phase status and completion progress. It uses a specific verb and resource. However, it does not explicitly distinguish from the sibling tool 'get_threat_model_progress', which might have overlapping functionality. Thus, it earns a 4 rather than a 5.
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. There is no mention of exclusions, prerequisites, or comparisons to sibling tools like 'get_threat_model_progress' or 'get_threat_modeling_plan'. The only context is the purpose statement, which implicitly suggests use for checking phase status, but no explicit usage guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/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 mentions returning markdown-formatted output, which is helpful, but it does not explicitly state that this is a read-only operation with no side effects, nor does it describe error behavior (e.g., what happens if the ID is not found) or any required permissions. This is a significant gap for a retrieval tool.
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 short but redundant: 'Get details about a specific trust zone' is restated as 'This tool retrieves details about a specific trust zone in the system architecture.' This repetition wastes a sentence. The Args and Returns sections provide useful structural clarity, but the redundancy and undocumented 'ctx' parameter detract from the overall conciseness.
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?
For a simple one-parameter getter, the description covers the essentials: what it does and what it returns. However, it does not address error scenarios (e.g., missing or invalid ID) or confirm the read-only nature, and the output schema is not visible to validate the return description. The tool is simple enough that this is acceptable, but it could be more complete with a note on not modifying state.
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 the only parameter 'id' with the exact description 'ID of the trust zone to retrieve', and the description repeats this without adding new meaning. The mention of 'ctx' in the Args section is confusing because it is not present in the input schema, potentially misleading the agent into thinking it is a required or available parameter. Since schema coverage is 100%, the baseline applies.
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 'Get details about a specific trust zone' clearly states the action (retrieve) and resource (trust zone), with 'specific' differentiating it from listing all trust zones. This unambiguously distinguishes it from sibling tools like list_trust_zones, add_trust_zone, update_trust_zone, and delete_trust_zone.
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 explicit guidance on when to use this tool versus alternatives like list_trust_zones for enumeration or update_trust_zone for modifications. There are no stated prerequisites or exclusions, leaving the agent to infer usage solely from the tool's name and purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior, but it only states the action and that a confirmation message is returned. It does not clarify idempotency, behavior if the link already exists, or any side effects. This is a significant gap for a mutation-like operation.
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 somewhat redundant: the opening sentence repeats the intent of the second paragraph. The Args section is useful but could be tightened. It is still relatively brief, but not optimally concise.
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?
For a simple linking tool, the description covers the basics: action, required args, and return value. However, it omits behavioral context (e.g., idempotency) that would be valuable given the lack of annotations. The presence of an output schema mitigates some absence of return 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 0%, so the description compensates by explaining each parameter: 'mitigation_id: ID of the mitigation to link' and 'threat_id: ID of the threat to link to.' This adds meaning beyond the schema titles, though it lacks details like format or existence requirements.
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: 'Link a mitigation to a threat.' It uses a specific verb and resource pair, and the scope ('in the threat model') is mentioned. This distinguishes it from related tools like unlink_mitigation_from_threat.
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 versus alternatives (e.g., unlink_mitigation_from_threat) or any prerequisites such as mitigation and threat existing. The context is implied only by the action, with no explicit exclusions or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description is expected to disclose side effects, but it only says the connection is removed and a confirmation message is returned. It does not explain whether the connection is deleted, what happens to related data, or whether errors occur if the crossing point or connection does not exist.
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 short but redundant: the first sentence 'Remove a connection from a crossing point.' and the second sentence 'This tool removes a connection from a crossing point...' say essentially the same thing. The docstring-style Args/Returns section is useful but adds little new 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?
Given the simplicity of the tool (two string parameters, no nested objects), the description provides a basic explanation of the operation and return value. However, it omits edge cases, side effects, and contextual usage relative to sibling tools, so it is only minimally 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 covers both parameters with identical descriptions, giving 100% schema coverage. The description adds no additional meaning beyond what the schema provides, and it also mentions a `ctx` parameter that is not part of the schema, which could be confusing.
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 'Remove a connection from a crossing point' and repeats the action with the resource named in the tool name. It is specific and semantically distinct from the sibling `add_conn_to_crossing` since removal is the inverse operation.
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 such as `delete_crossing_point` or `update_crossing_point`. There is no mention of prerequisites, exclusions, or which scenarios call for this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It states the tool 'generates all required documentation and outputs' and returns a markdown report, but it does not mention side effects (e.g., whether it modifies state), idempotency, permissions, or failure modes. This is a significant gap for a tool that 'executes' a step.
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: two sentences plus a small Args/Returns block. Every sentence carries meaning, and there is no redundancy or fluff. It efficiently conveys the core action and return format.
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 includes the purpose, the single context input, and the return format, which is reasonable for a zero-parameter tool. However, it lacks usage context (e.g., prerequisites, side effects, or relation to other tools). Given the absence of annotations and the presence of an output schema, the description is minimally viable but not rich enough to fully inform an agent about when and how to safely 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 input schema has zero properties, and the description mentions an 'Args: ctx' that is not in the schema, likely an auto-injected context parameter. Since there are no user-facing parameters to explain, the description's brief mention of 'ctx' for logging is sufficient. The baseline for 0 params is 4, and no additional parameter semantics are needed.
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's action: 'Execute the complete final export step (Phase 9) automatically.' It identifies the resource (the final export) and the action (execute/generate). However, it does not explicitly differentiate from sibling export tools like 'export_comprehensive_threat_model' or 'export_threat_model_with_remediation_status', relying on 'Phase 9' for context.
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 explicit guidance on when to use this tool versus alternatives. It does not mention preconditions (e.g., completing earlier phases) or exclusions. The 'Phase 9' reference implies a specific point in a workflow, but without naming alternatives or conditions, the agent is left guessing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/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 mentions the output is markdown-formatted with prompts for LLM analysis and uses AI-powered analysis, but it does not disclose whether the operation is read-only, has side effects, or requires certain conditions. Critically, the description introduces a 'ctx' argument that is not present in the input schema, which is misleading.
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 relatively short and front-loaded with the main purpose, but it includes an unnecessary Args section that is inconsistent with the schema and repeats the plan concept. Some sentences add little value beyond the first line.
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?
This is a simple zero-parameter tool, but the description is not fully complete. It lacks context on how this plan fits into the overall threat modeling workflow and what the plan will contain beyond 'prompts for LLM analysis'. The misleading ctx argument also 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?
The input schema has zero parameters, so the baseline is 4. However, the description describes an 'ctx' parameter that does not exist in the schema, adding confusion rather than meaning. Since the description contradicts the schema, it fails to provide useful 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 clearly states the tool gets a business context analysis plan, using the specific verb 'Get' and resource 'business context analysis plan'. It further explains the plan is for analyzing business context descriptions and categorizing business features, which distinguishes it from sibling tools like get_architecture_analysis_plan.
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 implies the tool should be used when a business context analysis plan is needed, but it does not explicitly state when to use it versus alternatives or mention any exclusions. No prerequisite or workflow context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/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 'returns a markdown-formatted list' but does not explicitly state whether it is read-only, requires specific permissions, or what happens on invalid model names. The only behavioral trait beyond the obvious is the output format.
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 compact but contains redundancy: the first sentence and second sentence convey the same information. The Args/Returns structure is clear, but the inclusion of a non-schema parameter (ctx) is unnecessary. Still, it's efficiently sized for a one-parameter tool.
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 getter with a single parameter and an output schema, the description covers purpose, parameter, and return format. It doesn't discuss error handling or when to use it, but given the low complexity and available output schema, it is reasonably 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?
Schema coverage is 100%, and the description repeats the model_name parameter exactly without adding syntax or value constraints. It also lists an 'ctx' argument that is not present in the input schema, which could mislead the agent. No examples or default values are 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 opens with 'Get available types for a data model' and clarifies 'returns the available types for a specified data model,' using a specific verb ('get'/'returns') and resource ('data model') with a clear scope. This distinguishes it from sibling tools like list_data_models or validation tools.
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, prerequisites, or exclusions. The description only states what it does, not when to call 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, the description must carry behavioral transparency. It states the return format (markdown-formatted list) and mentions the filtering parameters, which gives some transparency about scope. However, it does not explicitly state that the operation is read-only, nor does it disclose any potential side effects, ordering, or pagination behavior. The inclusion of a non-existent 'ctx' argument in the description also creates confusion about the expected call signature.
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 has a clear structure with Args and Returns sections, but the first two sentences are redundant ('List all threat actors.' and 'This tool lists all threat actors in the threat model.'). This redundancy wastes space. The inclusion of the phantom 'ctx' argument adds unnecessary noise. Overall, it is not a model of conciseness.
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?
For a simple list tool, the description covers the core purpose, parameters, and return type. However, it lacks explicit confirmation that this is a non-destructive read operation, and the misleading 'ctx' argument introduces uncertainty about invocation. The description does not mention error conditions or how the output is ordered, but for a straightforward listing tool, these gaps are moderate.
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 already provides full descriptions for both parameters (type and relevant_only), and the description merely repeats these without adding new meaning. Moreover, the description introduces an 'ctx' parameter that is absent from the schema, which could mislead the agent into passing an invalid argument. This is a net negative for 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 clearly states the tool's function: 'List all threat actors.' It identifies the specific resource (threat actors) and the action (list), distinguishing it from sibling list tools like list_components or list_data_stores. The additional sentence 'This tool lists all threat actors in the threat model' reinforces the scope.
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 for individual threat actor details one should use get_threat_actor, or that analyze_threat_actors might be more appropriate for analysis. There are no when-not-to-use conditions or references to sibling tools.
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, the description carries the full burden. It discloses the return format (markdown) and content (completed phases, current phase), but does not explicitly state read-only behavior or any session requirements. For a getter, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively concise but has redundancy ('current progress' repeated) and includes an irrelevant Args section for 'ctx' that isn't in the schema. Structure is clear but not optimally front-loaded.
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 zero-parameter getter with an output schema, the description provides sufficient information about the returned markdown progress report. It could clarify the relationship with get_current_phase_status, but that falls under usage guidelines rather than completeness.
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 tool has zero parameters, so the baseline is 4. The description adds no parameter information, which is fine since none are needed. It does mention a 'ctx' argument not present in the schema, which is minor noise.
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 retrieves the current threat modeling progress, including completed phases and the current phase. It differentiates from get_current_phase_status by mentioning completed phases, but does not explicitly name 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 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 versus alternatives like get_current_phase_status. There is no mention of exclusions, prerequisites, or specific scenarios where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/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 only states the reset action and mentions a confirmation message, but fails to explain what happens to existing custom actors, whether the operation is destructive, or if it is reversible. For a mutation tool, this is insufficient.
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 short but contains redundant phrasing: 'Reset the threat actors to the default set.' and 'This tool resets the threat actors to the default set.' The first sentence serves as the purpose, while the second is redundant. The Args/Returns structure is clear but adds unnecessary repetition.
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 that this is a reset operation with no annotations, the description is too sparse. It doesn't clarify what the 'default set' consists of, nor whether the operation is destructive or reversible. The output is only described as 'a confirmation message', which is vague. More context is needed for an agent to understand the consequences.
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 no parameters, so the baseline is high. The description mentions an 'ctx' parameter for logging and error handling, but this is not present in the schema and could confuse the agent into attempting to pass it. Since there are no user-facing parameters, the description adds minimal value 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 uses a specific verb 'reset' and clearly names the resource 'threat actors' with an outcome 'to the default set'. This distinguishes it from sibling tools like 'clear_threat_actors' (removal) and 'delete_threat_actor' (individual removal).
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 implies the use case of restoring default threat actors but provides no explicit guidance on when to choose this over clear_threat_actors or delete_threat_actor. There are no mentions of alternatives or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/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 only states that deletion occurs and returns a confirmation message, without covering permanence, cascading effects, permissions, or error behavior.
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 organized into short sections but includes an extraneous Args entry for 'ctx' and some repetition. It is still relatively concise and front-loaded with the core purpose.
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 basic delete functionality and batch mode, but lacks edge-case handling, confirmation details, and clarity on the relationship between 'id' and 'ids'. The erroneous 'ctx' parameter further 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?
The description repeats schema information without adding meaningful detail, and incorrectly includes a 'ctx' parameter not present in the input schema, which could mislead an agent. It also omits the schema's note that 'ids' overrides '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 clearly states the tool deletes an assumption from the threat model, using a specific verb and resource. It also distinguishes batch and single-item modes, differentiating it from sibling assumption 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?
It provides explicit instructions for single-item and batch usage via the 'ids' parameter, which helps an agent decide how to invoke the tool. However, it does not mention alternatives or when-not-to-use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It only mentions returning a confirmation message and does not state that deletion is irreversible or discuss side effects on related entities (e.g., connections). Additionally, it lists a 'ctx' parameter that is not in the input schema, which could mislead an agent.
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 contains redundancy, repeating that the tool deletes crossing points multiple times. While it is not overly long, the repetition wastes space and could be tightened to a more concise format.
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?
For a simple delete tool with a rich schema and output schema, the description covers the basic operation but misses important context: no mention of irreversibility, what happens if neither parameter is provided, or potential impacts on linked connections. This leaves gaps for an agent to safely use the 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 schema provides 100% coverage for parameters, so baseline is 3. However, the description introduces an undocumented 'ctx' parameter, which adds confusion. The descriptions for 'id' and 'ids' add minimal value since the schema already explains the batch behavior and ignoring 'id' when 'ids' 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 the tool deletes crossing points, using a specific verb and resource. It also mentions batch operations, distinguishing it from sibling CRUD tools like add_crossing_point or update_crossing_point.
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 explicit usage instructions for both single and batch deletion modes. However, it does not state when not to use the tool or mention any prerequisites or exclusions, but the context is clear enough.
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 burden of disclosure. It states it returns a markdown guide and that phase is optional, indicating a read-only, informational tool. However, it does not explicitly state it does not mutate state or require prior setup, and the mention of 'ctx' for logging/error handling is vague.
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 concise and well-structured with a title, a short paragraph, and clear Args/Returns sections. It includes 'ctx' which is not in the schema, slightly reducing efficiency, but overall it 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 simplicity (one optional parameter, output schema exists, no nested objects), the description is sufficiently complete. It explains the purpose, parameter, and return format. It could improve by clarifying the relationship with get_phase_*_guidance tools, but no critical information 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?
The only schema parameter 'phase' is well described in the description: 'Optional phase to get guidance for (if not provided, will use current phase)', adding meaning beyond the schema's type and default. The 'ctx' arg mentioned in the description is not part of the input schema, which could cause confusion.
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 guides the user through the threat modeling process step by step, following the plan from get_threat_modeling_plan, and returns a markdown-formatted guide. It distinguishes from get_threat_modeling_plan by referencing it as the source of the plan, but does not explicitly differentiate from sibling tools like get_phase_X_guidance.
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 implies usage after generating a plan but provides no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives such as get_phase_1_guidance or get_current_phase_status, leaving the agent to infer the right context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of disclosing behavior. It only states that it retrieves details and returns a markdown description, but does not explicitly confirm that it is read-only, whether it requires specific permissions, or how it handles non-existent IDs. This is a gap for a tool in a system with many mutating operations.
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 contains redundancy: the first line and the second sentence essentially repeat the same information. The inclusion of 'ctx' in the Args section adds unnecessary detail not aligned with the schema. Otherwise, the structure is clear with Args and Returns sections, but it is not as concise as it could be.
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 retrieval tool with one parameter and an existing output schema, the description provides enough to understand the resource and return format. It does not mention edge cases or additional context, but for a straightforward getter, this is adequate. The lack of usage guidance is a minor gap, but the tool's simplicity reduces the need for more.
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 includes an 'Args' section explaining 'id: ID of the flow to retrieve,' adding meaning beyond the schema, which only names the parameter. This compensates for the 0% schema description coverage. However, it also mentions a 'ctx' parameter not present in the input schema, which could be confusing.
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 'Get details about a specific asset flow,' which clearly identifies the action (get details), the resource (asset flow), and the scope (a specific one). This distinguishes it from sibling tools like list_flows or get_asset_flow_analysis_plan.
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 versus alternatives such as list_flows or other getters. The description does not mention any context, prerequisites, or exclusions, leaving the agent without direction for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/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 for behavioral transparency. It mentions the return format (markdown list) and the optional type filter, but it does not disclose any behavioral traits such as side effects (though 'list' implies read-only), pagination, ordering, or scope restrictions. For a tool with no annotations, this is a notable gap in transparency.
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 relatively short but contains redundancy: 'List all trust boundaries' and 'This tool lists all trust boundaries' convey the same information. The Args/Returns structure is clear, but the opening repetition adds unnecessary length. Overall, it is compact but not optimally 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?
For a simple list tool with an output schema (which covers return values), the description adequately explains the purpose and arguments. It does not provide context on when to use it or what types are available, but given the simplicity and the presence of an output schema, the description is sufficiently complete for an agent to 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?
The input schema has 100% coverage: the only parameter 'type' is described in the schema as 'Optional type to filter trust boundaries'. The description repeats this exact phrase without adding new meaning, such as valid values or examples. The mention of 'ctx' is likely an internal context parameter not in the schema, but it does not clarify user-facing parameters. Baseline of 3 applies due to full 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 'lists all trust boundaries' with a specific verb and resource. It repeats the purpose in the second sentence ('lists all trust boundaries in the system architecture'), which reinforces the action. This distinguishes it from sibling tools like get_trust_boundary (single retrieval) and clear_trust_boundaries (delete all).
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 when-to-use or alternative guidance is provided. The description implies that this tool is for listing all trust boundaries, but does not explicitly say 'use this instead of get_trust_boundary' or mention any exclusions. The sibling context suggests list vs. get, but the description itself does not articulate these distinctions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/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 states the operation and return value but omits side effects, validation requirements, idempotency, and error behavior. The mutation nature is implied but not elaborated.
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 Args/Returns sections and is not overly long. However, the first two sentences are redundant ('Unlink...' and 'This tool unlinks...'), wasting a sentence. The formatting aids readability but this redundancy slightly lowers the score.
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 tool is simple (two string params, no enums), and the description includes return behavior. But it lacks usage guidance, prerequisites, or relationship to the inverse link operation, and the context is minimal for an agent to invoke confidently in a larger workflow.
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 names each parameter and explains their roles ('ID of the mitigation to unlink', 'ID of the threat to unlink from'), compensating for the 0% schema description coverage. However, it does not specify ID format or how to obtain them, so it is not fully complete.
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 'Unlink' with the resource 'mitigation' and 'threat', clearly distinguishing it from the sibling tool 'link_mitigation_to_threat'. The action is unambiguous and directly maps to the tool's name.
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 or when to prefer alternatives. It simply restates the operation without contextual cues like 'use after linking' or prerequisites, leaving the agent to infer appropriate usage from the sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose side effects and constraints. It mentions that it adds flows and returns confirmation with flow ID(s), but does not describe validation rules, prerequisites (e.g., whether referenced assets/trust zones must exist), idempotency, or error behavior. This lack of context is a significant gap 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with sections (Args, Returns) and is mostly efficient. However, the first line 'Add a new asset flow to the system' is repeated nearly verbatim in the second paragraph ('This tool adds one or more asset flows to the system'), which is redundant and could be tightened.
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 tool's complexity (13 parameters, no annotations, 0% schema coverage), the description covers the primary purpose and parameter semantics, but lacks critical contextual details. It does not specify validation behavior, dependencies on other entities (assets, trust zones), or the exact shape of batch items. The presence of an output schema partially mitigates the missing return-value details, but overall completeness remains moderate.
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 description coverage is 0%, so the description must compensate. It provides a parameter list with meaningful descriptions (e.g., 'ID of the asset being transferred', 'Risk level of the flow (1-5)') and clarifies that asset_id, source_id, and destination_id are required for single-item mode. However, it does not detail the structure of items for batch mode, which is a notable omission.
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 ('Add a new asset flow to the system') with a specific verb and resource. It distinguishes itself from sibling tools by focusing on asset flows and mentions batch operations via the 'items' parameter, which adds clarity.
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 how to use single vs. batch modes ('provide asset_id, source_id, destination_id, and optional fields directly' vs. 'provide a list of flow dicts in the items parameter'), which is useful. However, it does not explicitly state when to use this tool over alternatives (e.g., update_flow) or provide any 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It states the operation deletes threats and returns a confirmation message, but it does not disclose whether deletion is permanent, whether there are cascading effects on related entities (e.g., mitigations), or if any confirmation/permissions are needed. This is insufficient 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured into sections (overview, usage, args, returns) but contains redundancy (e.g., the first sentence repeats 'Delete a threat' twice) and includes the non-schema 'ctx' parameter, adding noise. It could be tighter.
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?
For a simple CRUD delete, the description covers the basics: what it does, how to use single vs. batch, and return value. However, it lacks edge-case behavior (e.g., nonexistent threat), side effects, and any dependencies, while having no annotations or schema descriptions to back it up. It is minimally complete but not thorough.
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 0%, so the description must compensate. It explains 'id' for single deletion and 'ids' for batch, and their roles. However, it misleadingly includes 'ctx' which is not in the schema, and it does not clarify behavior when both 'id' and 'ids' are provided or the mutual exclusivity implied.
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 deletes a threat from the model, with specific verb ('Delete') and resource ('threat'), and explicitly mentions batch operation support. This distinguishes it from sibling threat operations like add, list, get, and 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?
Provides clear usage instructions for single vs. batch modes, including which parameter to use in each case. It does not explicitly mention alternatives or exclusions, but the context is straightforward enough for the agent to know 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.
- Behavior2/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 basic delete behavior and return of a confirmation message, but omits crucial details such as permanence, cascading effects on linked entities, or error handling. The behavior when both 'id' and 'ids' are provided is left to the schema rather than the description.
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 structured with sections, but the opening sentence 'Delete a threat actor' is immediately repeated in the next sentence, creating redundancy. The Args and Returns sections also echo schema information without adding value. A more concise version would merge the redundant statements.
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?
For a simple delete tool with an output schema, the description is adequate but not complete. It does not differentiate from clear_threat_actors for bulk deletion, nor does it mention preconditions (e.g., whether the actor must exist) or potential implications of deleting an actor that is referenced elsewhere.
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 covers both parameters with 100% description coverage, including the precedence of 'ids' over 'id'. The description adds redundant mode explanations but does not introduce new semantic details beyond the schema. The mention of 'ctx' as an argument not present in the schema could cause confusion.
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 'Delete a threat actor' with a specific verb and resource, and explicitly mentions batch operations. This distinguishes it from sibling tools like add, update, list, or get threat actors.
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 single vs batch deletion via the 'id' and 'ids' parameters. However, it does not contrast this tool with alternative bulk operations like clear_threat_actors or reset_threat_actors.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits such as side effects, file format, or required system state. It only states that it exports and returns a confirmation message, lacking details about overwrite behavior, output format, or any permission requirements. This is minimal and does not fully carry the burden.
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: a one-sentence summary, an elaboration, then clear Args and Returns sections. No redundant content, and each sentence serves a purpose. The only minor issue is the ctx parameter, but overall layout is excellent.
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?
For a simple one-parameter export tool, the description covers purpose and parameter meaning. However, it omits important contextual details like the output file format, whether the file will be overwritten, or how this export differs from other similar tools. The existence of an output schema reduces the need to explain return values, but the description still feels incomplete for fully autonomous agent use.
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 only lists output_path with no description, so the description adds value by explaining 'Path to save the exported threat model'. However, it also mentions an undocumented 'ctx' parameter, which may confuse agents about what arguments are actually expected. Despite this, it compensates well for the schema's 0% 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 specific verb 'export' and the resource 'threat model with remediation status'. It further clarifies the unique scope: 'information about which threats are already remediated by existing security controls', which distinguishes it from sibling tools like export_comprehensive_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 Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool vs alternatives. It doesn't mention any exclusions, prerequisites, or compare to other export tools. The usage context is only implied through the name and focus on remediation status, but there is no concrete direction for the agent.
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 transparency burden. It mentions it 'retrieves' data (implying read-only) and discloses the return format as 'markdown-formatted description.' However, it does not discuss error scenarios, permissions, or idempotency. The added markdown detail is useful but limited.
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 short but contains redundancy: the first sentence and the second sentence essentially repeat the same information. The Args/Returns structure is clear, but the duplicate statement could be removed. Slightly under-optimized for conciseness.
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?
For a simple retrieval tool with one parameter and an output schema, the description covers the core purpose and return format. However, it lacks usage guidance, relation to siblings, and any prerequisites or error conditions. The context signals indicate a low-complexity tool, so a moderate score is appropriate.
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 100%, and the description adds no extra meaning beyond the schema. The parameter 'id' is described consistently as 'ID of the trust boundary to retrieve' in both places. As per the rubric, high schema coverage leads to a baseline of 3, and no additional semantic value 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 provides a clear verb+resource combination: 'Get details about a specific trust boundary.' It clearly indicates the tool retrieves details for a single trust boundary, distinguishing it from sibling tools like list_trust_boundaries or add_trust_boundary. The phrase 'in the system architecture' adds helpful context.
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?
Usage guidance is implied: the tool is used when an ID is known and details are needed. However, the description does not explicitly state when to use this tool versus alternatives like list_trust_boundaries or get_trust_boundary_analysis_plan. There is no mention of when-not-to-use or alternative recommendations.
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 transparency burden. It discloses that the plan is AI-powered, validated against AWS documentation, and returns markdown with prompts for LLM analysis, which is useful beyond a simple 'returns plan' statement. It doesn't explicitly state side effects, but as a getter, the behavior is largely transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The first sentence is a near-tautology of the tool name, repeating 'get a comprehensive trust boundary analysis plan.' The 'Args' section introduces a non-schema parameter that adds confusion, and the structure is somewhat padded.
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 tool is simple with no parameters and has an output schema, so return values are covered. However, given the large list of sibling plan-related tools, the description lacks enough context to help an agent choose between this and similar plans like get_trust_boundary_detection_plan or get_architecture_analysis_plan.
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 tool has zero parameters and the schema is empty, so the baseline is 4. The description mentions a 'ctx' arg for logging, which is not in the schema and may confuse, but it doesn't need to describe actual parameters. The extra mention is not meaningful but doesn't undermine the baseline.
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 returns a detailed plan for analyzing trust boundaries, specifying the resource and purpose. It doesn't explicitly differentiate from sibling tools like get_trust_boundary_detection_plan or get_architecture_analysis_plan, but the focus on 'analysis' and 'security concerns' provides enough clarity.
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 implies usage when a trust boundary analysis plan is needed, but it provides no explicit when-to-use or when-not-to-use guidance. No alternatives or exclusions are mentioned, so the context is only lightly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/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 fails to disclose whether updates are partial or full replacement, behavior on missing ids, or whether batch updates are atomic. The 'Returns' is vague, and key side effects are unaddressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description front-loads the key purpose but then includes a full Args section that duplicates the input schema descriptions. This redundant documentation adds bloat instead of earning its place.
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?
Despite having an output schema, the description omits critical behavioral details for a complex 9-parameter tool: partial vs full update semantics, error handling for missing components, batch atomicity, and behavior when neither id nor items is provided. These gaps make it incomplete.
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 100%, but the description adds semantic value by clarifying the relationship between id and items, explaining that single mode requires id while batch mode uses items. This goes beyond the individual 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 clearly states the tool updates existing components in the architecture, with explicit mention of batch operations. It distinguishes itself from sibling tools like add_component and delete_component by focusing on updating existing 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 tool explains two usage modes (single vs batch) and how to structure calls in each. However, it does not explicitly state when to prefer this tool over alternatives, such as using add_component if the component doesn't exist.
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?
Since no annotations are provided, the description carries the full burden. It clearly states the tool analyzes the codebase and generates a report, which conveys its main behavior. However, it does not disclose whether the tool modifies anything, requires specific permissions, or could be time-consuming. This is adequate but lacks depth on side effects or 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 well-structured with a clear intro, explanation, Args section, and Returns section. It is appropriately sized with no redundant information. The markdown formatting and front-loaded main purpose make it easy to scan and understand.
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 aspects: purpose, parameters, and return value ('A markdown-formatted validation report'). Given that an output schema exists, it need not detail the report structure. However, it lacks context about prerequisites or how this fits into the broader workflow, which is a minor gap given the tool's complexity.
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 0%, so the description must compensate. It does so by explaining code_directory as 'Directory containing code to analyze' and file_patterns as 'Optional list of file patterns to include (e.g., ["*.py", "*.js"])'. This adds meaningful context beyond the schema's minimal titles, including an example for file patterns.
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's function: 'Validate the threat model against the actual codebase.' It also explains it analyzes the codebase to determine which threats are mitigated by existing security controls and generates a report. This is specific and actionable, but it does not explicitly differentiate from sibling tools like validate_security_controls or execute_code_validation_step, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, such as having a threat model defined, or when in the workflow this should be run. The only implicit context is the tool's name and description, but no direct usage recommendations or exclusions are given.
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, the description carries the transparency burden. It states the tool 'retrieves details' and returns a 'markdown-formatted description', implying a read-only operation with a defined output format, but does not disclose potential errors 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The opening sentence is redundant ('Get details about a specific asset' and 'This tool retrieves details about a specific asset'). The Args/Returns structure is efficient but the repetition could be removed.
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 getter with one parameter and an output schema, the description covers the action, the parameter meaning, and the return format. It is slightly thin on error behavior, but adequate for a straightforward retrieval 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 provides no descriptions for 'id' (0% coverage). The description compensates by explaining 'id: ID of the asset to retrieve' and also documents a 'ctx' argument, though that is not in the schema. This adds meaningful semantics for the only 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 uses the specific verb 'Get' and identifies the resource as 'a specific asset', clearly distinguishing from list_assets and other get_* tools in the sibling set.
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 over alternatives such as list_assets, nor does it mention any prerequisites or exclusion scenarios.
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, the description carries the full burden. It communicates a read-only nature via 'retrieves' and mentions that the return is markdown-formatted. However, it does not explicitly state that no modifications occur, nor does it disclose behavior for non-existent IDs or any error handling. The lack of side-effect disclosure is partially mitigated by the non-destructive verb.
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 generally concise but has redundant sentences: 'Get details about a specific threat' and 'This tool retrieves details about a specific threat in the threat model' say the same thing. It also includes a 'ctx' argument that is not in the schema, adding unnecessary noise. The structure with Args/Returns is clear, but redundancy and extraneous info reduce efficiency.
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 getter with one parameter and an output schema, the description adequately covers purpose, the required parameter, and return format. It does not specify error behavior or usage distinctions, but those are less critical for this basic read operation. The presence of an output schema (though not shown) reduces the need to detail return values. Overall, it is reasonably 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?
Schema description coverage is 0%, so the description must compensate. It explains the sole parameter 'id' as 'ID of the threat to retrieve', adding meaning beyond the bare schema property. However, it also mentions a 'ctx' parameter that is absent from the schema, which could confuse an agent. The overall semantic contribution is strong for the actual 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 tool's function with a specific verb and resource: 'Get details about a specific threat' and 'retrieves details about a specific threat in the threat model.' It distinguishes from sibling tools like list_threats by emphasizing a single threat rather than a list.
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 versus alternatives. There is no mention of situations where list_threats would be more appropriate, or any prerequisites or exclusions. The usage context is only implied through the 'get' pattern.
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 should disclose behavioral traits. It mentions the return value (confirmation message with feature count) and the elimination of the clarification workflow, but it does not state whether existing context is overwritten, what happens to omitted fields, or whether any validation occurs. This is partial transparency 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The opening two sentences are concise and impactful, and the Returns line is useful. However, the detailed Args block redundantly duplicates the schema's property descriptions, adding length without value. The structure is acceptable but not tightly edited.
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 high parameter count and existing output schema, the description provides a basic overview and return value but leaves gaps about side effects, overwrite behavior, and how this relates to other sibling tools. It is minimally adequate for a tool of this complexity.
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 already provides 100% description coverage for all 11 parameters, so the description's parameter list adds no new meaning. Worse, it includes 'ctx' as an argument, which is not present in the schema, potentially misleading an agent into sending an invalid parameter. This is a net negative 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 it 'sets the business context description and all business features in a single call,' using a specific verb and resource. It differentiates from siblings like 'get_business_context' and 'clear_business_context' by focusing on the set operation and explicitly mentions eliminating the clarification questions workflow.
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 when to use this tool by emphasizing it is a streamlined single-call alternative to the clarification questions workflow. However, it does not explicitly discuss alternatives or state when not to use it, leaving some room for interpretation.
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 of behavioral disclosure. It reveals that the tool updates one or more existing connections, supports batch operations, and requires each batch item to include 'id'. It also states the return value is a confirmation message. However, for a mutation tool, it does not disclose side effects, error behavior, reversibility, or permission requirements, leaving significant gaps.
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 first-line summary, a brief explanation of modes, an Args list, and a Returns section. It is front-loaded with the core purpose. However, the Args list largely duplicates schema descriptions, adding length without new information, though it remains reasonably concise overall.
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?
This is a moderately complex tool with 8 parameters and batch support. The description adequately explains the two usage modes and batch requirements, but lacks information on partial updates, error handling, or how this tool differs from other update_* tools. An output schema exists, so return details are not needed, but the description still has notable gaps for a tool of this 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 100%, so the schema already documents all parameters. The description adds some usage semantics (single vs batch modes) but mostly restates the schema descriptions (e.g., 'New ID of the source component'). It also introduces a 'ctx' argument that does not appear in the input schema, which is confusing and adds minimal value 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 the tool's purpose: 'Update an existing connection in the architecture' and mentions batch support via 'items'. This is a specific verb+resource pair. However, it does not distinguish this tool from sibling update_* tools (e.g., update_component, update_data_store), so it lacks explicit differentiation.
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 for both single and batch modes: 'For single item: provide id and fields to update directly. For batch: provide a list of connection dicts in the 'items' parameter.' It also explains that each batch item must include 'id'. However, it does not mention when to prefer this tool over alternatives or when not to use it, so exclusions and alternatives are missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/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 says the tool 'updates' but does not disclose side effects, required permissions, reversibility, behavior when the boundary does not exist, or whether omitted fields are left unchanged. The batch behavior is already described in the schema, so the description adds little new safety context.
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, mode explanation, an Args list, and Returns. It is slightly repetitive of the schema descriptions, but remains readable and front-loaded with the most important information about batch vs single operation.
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 tool has 7 parameters, no annotations, and an output schema. The description covers usage modes and the return value ('A confirmation message'), but lacks information on error handling, idempotency, and safety. It is adequate for a tool with fully documented schema parameters, but not fully comprehensive.
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 100%, so the baseline is 3. The description adds value by explaining mode-specific requirements (e.g., id required for single item mode, items for batch) and noting that batch ignores individual parameters. However, it also lists a 'ctx' parameter that is not present in the input schema, which adds confusion and slightly detracts from clarity.
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 an existing trust boundary,' which is a specific verb+resource statement. It further explains single vs batch modes, and the entity being updated (trust boundary) clearly distinguishes it from sibling update_* tools for other entity types.
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 context for usage: 'For single item: provide id and fields to update directly. For batch: provide a list of trust boundary dicts in the items parameter.' It does not explicitly name alternatives or when-not-to-use, but it clearly explains the two operational modes.
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. It discloses the side effect (adds crossing points), the return value (confirmation message with IDs), and the mutual exclusivity of single vs batch modes. However, it omits edge-case behaviors such as duplicate handling, validation errors, or whether batch operations are atomic, leaving some behavioral uncertainty.
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 organized and starts with a clear overview, but it includes an Args section that duplicates parameter descriptions already present in the schema. This redundancy adds verbosity without new value. The core content is concise, but the overall structure could be tighter.
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 presence of an output schema and full schema coverage, the description adequately covers the main usage patterns and return behavior. However, it omits contextual prerequisites (e.g., existence of trust zones) and error-handling behavior, making it only partially complete for a user unfamiliar with the domain. It is adequate but not comprehensive.
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 all 6 parameters (100% coverage), including the nuance that items ignores individual parameters. The description's Args section largely repeats the schema, adding only a high-level usage summary. Since schema coverage is high, the description adds minimal value beyond the baseline.
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 'Add a new crossing point' and then elaborates 'This tool adds one or more crossing points between trust zones in the system architecture.' This identifies the specific create operation and distinguishes it from sibling tools like update_crossing_point and delete_crossing_point. The batch capability 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 explicitly explains two usage modes: single item (provide source_zone_id, destination_zone_id, and optional fields directly) and batch (provide items list). It also notes that when items is provided, individual parameters are ignored. This provides clear context, though it doesn't mention explicit when-not-to-use scenarios or alternative tool names.
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. It discloses the scope of destruction (all trust boundaries, crossing points, and trust zones) but does not explicitly warn about irreversibility or potential impact on related architecture elements. A confirmation message is mentioned as the return value.
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 concise and front-loaded, with the main behavior stated in the first two sentences. There is minor redundancy between the first sentence and the second paragraph, but the Args/Returns sections are standard and add 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?
For a straightforward clear/reset tool, the description adequately covers the main behavior and return value. It lacks details on side effects or edge cases, but the output schema supplies return structure, making it sufficiently complete for its complexity.
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 tool has zero input parameters, so the schema fully covers parameter semantics. The description mentions 'ctx' under Args, but this is not present in the schema, which could cause minor confusion. However, since there are no actual parameters, the baseline of 4 applies.
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 clears all trust boundaries, and expands to include crossing points and trust zones. The 'all' distinguishes it from single-delete siblings like delete_trust_boundary, making the purpose 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 Guidelines2/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 vs alternatives such as delete_trust_boundary or clear_architecture. It doesn't mention prerequisites, consequences, or when not to use it, leaving the agent to infer its role from the name and sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/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 states the action (delete) but gives no information about permanence, cascading effects on related entities (e.g., connections, flows), error handling, or permission requirements. For a destructive operation, this is a significant gap—an agent doesn't know what side effects 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a summary line and Args/Returns sections, but it contains redundancy: the first two sentences repeat the same idea, and the usage instructions appear both in prose and in the Args list. It is not overly long, but not every sentence earns its place, so it only partially meets conciseness standards.
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 tool is simple (2 params, no nested objects, output schema exists). The description covers purpose, usage modes, and return format. However, it omits essential behavioral context for a delete operation—such as whether deletion is permanent, what happens to dependencies, and possible error conditions. Given the simplicity, a bit more detail would make it 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?
Schema description coverage is 100%, providing a baseline of 3. The description adds value by explaining the single vs. batch modes and clarifying that 'id' is required for single mode. However, it also lists 'ctx' which is not in the schema, creating a slight ambiguity. The precedence rule (ids overrides id) exists in the schema, so no deduction for 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 'Delete a component from the architecture' with a specific verb and resource, and immediately mentions batch operations via the 'ids' parameter, which distinguishes it from sibling delete tools that likely only handle single items. The resource (component) is unambiguous and differentiates from other delete tools for connections, data stores, etc.
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: single item via 'id', batch via 'ids' list, and explains the difference. It does not explicitly name alternatives or exclusion criteria, but the resource-specific nature makes the appropriate context obvious. No prerequisites or conditions are mentioned, but the core when-to-use is implied strongly.
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 discloses the destructive nature of the operation and the batch behavior, but omits details such as permanence, potential cascading effects on related entities, permission requirements, or error behavior. The mention of a 'ctx' parameter not present in the schema adds slight confusion.
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 and structured with Args/Returns sections, but it contains redundancy between the first two sentences and repeats parameter information already present in the schema. It is not excessively long, but not as tight as it could be.
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 tool is simple, and the description covers single and batch deletion modes. However, with no annotations, the description leaves out critical behavioral details such as whether deletion is permanent, if there are side effects on connected components or crossing points, and what happens if the connection does not exist. An output schema exists, so return details are not needed, but safety and impact context is lacking.
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 includes full descriptions for both 'id' and 'ids', including the behavior when 'ids' is provided. The description mostly repeats this information and introduces a 'ctx' parameter that is not in the schema, adding no extra semantic value beyond what is already documented.
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—deleting connections from the architecture—with a specific verb and resource. It also explicitly mentions batch support via the 'ids' parameter, distinguishing it from other delete tools in the sibling set.
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 for single vs. batch deletion and explains which parameter to use. However, it does not explicitly discuss when to choose this tool over alternative delete tools or any exclusions, though the resource type is unambiguous.
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, the description must carry the burden. It discloses that the tool deletes one or more data stores and returns a confirmation message, but omits consequences like cascading deletions, reversibility, or permission requirements. Basic information given, but significant gaps remain.
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 somewhat redundant: the first sentence 'Delete a data store' is repeated in the second paragraph 'This tool deletes one or more data stores'. The Args section largely repeats schema descriptions. While structured, it could be more concise.
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 tool's simplicity and full schema coverage, the description is adequate, but it does not address side effects, prerequisites, or what happens if both id and ids are provided (only schema notes this). The existence of an output schema reduces the need to explain return values, yet dependency handling is absent.
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 100%, so the schema already defines both parameters and their relationship. The description adds a helpful single-vs-batch explanation, but also lists 'ctx' as an argument that is not in the schema, which could confuse. Overall, minimal added value 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?
Description clearly states 'Delete a data store from the architecture' with a specific verb and resource, and immediately distinguishes batch mode via 'ids' parameter. This differentiates it from sibling tools like delete_component or delete_connection.
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 for single-item vs batch usage: 'For single item: provide the id directly' and 'For batch: provide a list of IDs'. It does not explicitly exclude alternatives, but the tool's name and sibling set make the context clear. No misleading guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/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 the tool 'automates,' 'analyzes the codebase,' and returns a markdown report, but it does not disclose whether the tool modifies state, updates progress, requires a pre-existing codebase setup, or has side effects. This is a significant gap for an 'execute' tool that likely triggers a multi-step process.
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: a clear one-line summary, a brief explanatory sentence, and compact Args/Returns sections. No redundant phrases or unnecessary detail; every sentence earns its place.
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 core purpose and return format, and the output schema likely documents the exact report structure. However, it lacks context about prerequisites (e.g., architecture and threat model inputs), potential side effects, and how this step fits into the broader threat-modeling workflow. For a phase-execution tool, this is a noticeable completeness 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 has zero parameters, so the description does not need to explain parameter semantics. However, the description lists a 'ctx' argument for logging and error handling that is not present in the schema, which is slightly confusing but does not impact usability since it appears to be an internal MCP context rather than a user-facing 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 tool 'Execute[s] the complete code validation step (Phase 7.5) automatically' and explains what it does: analyzing the codebase to identify implemented security controls and mitigated threats. This specific verb+resource+scope distinguishes it from sibling validation tools like validate_security_controls and validate_threat_model_against_code, which are individual validations rather than the full phase automation.
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 implies this tool is used to run the entire code validation phase ('Phase 7.5') automatically, giving some context but no explicit when-to-use guidance or alternatives. It does not mention that users might prefer individual validation tools for targeted checks, nor does it state prerequisites or when not 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It discloses that the tool returns a markdown-formatted prompt and mentions the report contents (remediated, partially remediated, required implementation). However, it does not disclose potential side effects, dependencies on prior threat model data, or whether the generation is purely computational, leaving gaps in 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening sentence, summary of report contents, and Args/Returns sections. It is slightly repetitive ('Generate a prompt' appears twice) but remains efficient and front-loaded. Every section earns its place, though the Args section for ctx could be omitted since it is not a user-facing parameter.
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 is complete for a simple 0-parameter tool. It explains the output format (markdown prompt) and what the report covers. The output schema exists, so return values are already structured. Given the simplicity and good schema coverage, the description sufficiently covers the tool's context without needing extensive detail.
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 0 parameters and schema coverage at 100%, the schema already fully accounts for parameters. The description adds a note about 'ctx' for logging and error handling, which is not in the schema but is internal MCP context. This is acceptable, and the baseline of 4 for 0-parameter tools applies.
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 prompt for LLM to create a comprehensive remediation report.' It uses a specific verb ('generate') and resource ('prompt'), and explicitly distinguishes its output (a prompt, not the report itself) from sibling tools like export_threat_model_with_remediation_status that directly export reports.
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 explicit guidance on when to use this tool versus alternatives. There is no mention of when to choose this over export_threat_model_with_remediation_status or validate_threat_remediation. The context is implied but not stated, leaving the agent without clear selection criteria.
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, the description carries the burden. It discloses the return format (markdown) and takes an ID, but does not mention error behavior, read-only nature, or side effects. For a simple get, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient with a clear one-line summary followed by brief Args/Returns sections. No fluff, though the Args section partially duplicates schema 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?
For a single-parameter retrieval tool with a schema and output schema present, the description adequately covers purpose, input, and output format. It doesn't mention edge cases, but the simple nature and existing structured data make this 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 coverage is 100% and the description repeats the same 'ID of the threat actor to retrieve' text. It adds no additional meaning beyond the schema. The mention of 'ctx' is not in the schema and might be an implicit/hidden parameter, but it doesn't enhance understanding of the public 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 'Get details about a specific threat actor' with a specific verb ('get') and resource ('threat actor'). This distinguishes it from siblings like list_threat_actors (which lists all) and update/delete_threat_actor.
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?
Usage is implied by the name and description: retrieve details for a specific actor given an ID. No explicit alternatives or exclusions are stated, but the context is clear enough for a simple get operation. Siblings are not referenced.
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 clearly signals a read-only behavior through 'Get' and 'returns,' and discloses that the output is markdown-formatted with AI-powered analysis prompts. It also mentions the ctx argument for logging/error handling, but does not discuss any potential side effects or resource implications beyond that.
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 short overview, a detailed paragraph, and explicit Args/Returns sections. The first sentence is somewhat redundant with the tool name, but the overall length is appropriate and the information is presented clearly without 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?
For a zero-parameter tool, the description covers its purpose and return format sufficiently. However, the presence of a closely-named sibling 'get_trust_boundary_analysis_plan' creates ambiguity, and the description does not explain how this tool differs from that one or when each should be used, leaving the overall context incomplete.
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 has zero parameters, so the baseline is 4. The description adds extra context for the 'ctx' argument, explaining it is for logging and error handling, which is not represented in the schema. This is helpful, though there are no user-facing parameters to elaborate on.
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 a 'comprehensive trust boundary detection plan' and explains it returns a detailed plan for detecting trust boundaries from architecture components using AI-powered analysis. It is specific about the resource and action, though it does not explicitly contrast with the similarly named sibling tool 'get_trust_boundary_analysis_plan'.
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 implies usage when one needs a plan for trust boundary detection, and mentions 'using AI-powered analysis with step-by-step prompts and guidance.' However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any when-not conditions or provide direct comparison with the many sibling plan tools.
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 states that the return is a markdown-formatted list and mentions ctx for logging, but it does not explicitly disclose whether it is side-effect-free or requires special permissions. The read-only nature is implied by 'List'.
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 short and uses a clear Args/Returns structure. However, it redundantly repeats 'List all crossing points' in the first two sentences, which adds unnecessary 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?
Given it is a simple list tool with one optional parameter and an output schema, the description covers the purpose, filter capability, and return format. It could explicitly mention side-effect-free behavior, but the verb 'List' makes it clear enough.
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 describes zone_id with 100% coverage (identical text). The description repeats this information without adding new semantics. It also lists 'ctx' as an argument not present in the schema, which could confuse agents.
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 'List all crossing points' with a specific verb and resource. It distinguishes itself from get_crossing_point by highlighting the list scope and optional zone_id filter.
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 implies usage for listing all crossing points and mentions the optional zone_id filter, but it does not explicitly state when to use this tool versus alternatives like get_crossing_point 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?
No annotations are provided, so the description carries the full burden. It discloses that it returns a markdown-formatted list and supports an optional filter, but it does not mention potential side effects, permissions, ordering, or error behavior. For a read-only list operation, the description provides basic transparency but lacks depth.
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 concise and well-structured with clear Args/Returns sections. There is minor redundancy ('List all trust zones' is repeated in the first two sentences), but this does not significantly impair 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?
The tool is simple with one optional parameter and an output schema exists (though not shown). The description covers the return format (markdown list) and the filter option, which is sufficient for a basic list tool. Minor missing details like empty-list behavior are not critical.
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 100% and the parameter trust_level is already well-documented in the schema. The description only repeats the schema's parameter description ('Optional trust level to filter zones') without adding additional context, so it meets the baseline but does not exceed it.
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 ('List all trust zones') and resource ('trust zones'), making it specific and unambiguous. It distinguishes from sibling tools like list_trust_boundaries or list_data_stores by explicitly naming trust zones.
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 implies usage for listing trust zones but does not provide explicit guidance on when to use it over alternatives (e.g., get_trust_zone for a single zone or list_trust_boundaries for boundaries). There are no exclusions or explicit 'use this when' statements, but the purpose is clear enough.
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, the description carries the full burden of behavioral disclosure. It does state what gets cleared (business context, description, clarification questions), which adds value, but it omits whether the operation is irreversible, destructive, or scoped to certain data. The confirmation message is mentioned, but no side effects or limitations are 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 short, front-loaded with the main action, and includes only essential details: what is cleared, the context argument, and the return type. Every sentence serves a purpose, and the structure is clean and scannable.
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 tool with no parameters and an output schema, the description adequately covers the core behavior and return value. It lacks guidance on when to use it or what happens to associated data, but given the tool's simplicity, it is reasonably 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 input schema has zero parameters, so the baseline is 4. The description mentions an 'ctx' argument for logging and error handling, but it is not present in the schema, which could confuse an agent. However, since there are no documented parameters, the description does not need to add much 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 clearly states the tool's function with a specific verb ('Clears') and resource ('the business context'), and explicitly enumerates what is cleared ('description, and clarification questions'). This distinguishes it from sibling tools like set_business_context and get_business_context.
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 scenarios such as resetting context or mention sibling tools. Usage is only implied by the tool's name and the action 'clear', which is insufficient for an agent deciding between this and set_business_context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/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 only that the operation deletes and returns a confirmation message, but fails to mention irreversibility, potential side effects (like removing connected elements), or permission requirements. For a destructive operation, this is a significant gap.
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?
Structured with a purpose statement, mode explanations, Args, and Returns. Minor redundancy ('Delete an asset flow...' repeated) but overall concise and front-loaded.
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 basic modes and return type, but leaves ambiguity about parameter precedence (what if both 'id' and 'ids' are provided, or neither) and does not clarify that the schema allows both to be null. This is a notable gap for a tool with optional parameters.
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 clearly explains the 'id' and 'ids' parameters, including their single/batch roles and the fact that 'id' is required for single-item mode. This compensates for the schema's zero description coverage and adds meaningful 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 'Delete an asset flow from the system' with a specific verb and resource, and distinguishes from siblings by mentioning batch support via 'ids'. This makes the tool's 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?
Provides clear usage instructions for single and batch modes, but no explicit exclusions or comparisons to alternative deletion tools. The guidance is sufficient for most scenarios, though it could specify 'use this only for asset flows'.
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 the description carries the full burden. It does add value by disclosing the batch behavior and stating the return type ('Returns: A confirmation message'). Yet it fails to disclose important behavioral traits such as cascading effects on associated entities (e.g., crossing points), irreversibility, or error behavior when no arguments are provided, which are crucial 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the primary action and batch note, making the core purpose immediately clear. However, it becomes somewhat redundant: the first paragraph and the second paragraph repeat the same deletion behavior, and the 'Args' section duplicates schema definitions. Still, the overall length is manageable and mostly focused.
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 complexity is moderate (single vs batch delete), and the output schema richness is not provided. The description covers the main usage modes but leaves gaps: it does not specify what occurs when both id and ids are supplied (schema says id is ignored, but the description omits this), what happens with no arguments, or whether the deletion cascades to related architecture elements. These omissions prevent it from being fully 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 description coverage is 100%, so the baseline is 3. The description repeats the schema's parameter meanings and adds a 'ctx' argument that is not part of the exposed input schema, which could confuse an agent. It clarifies the single vs batch relationship but does not materially extend beyond the schema's existing descriptions, especially since the schema already notes that when ids is provided, id is ignored.
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 'Delete a trust boundary' – a specific verb and resource – and immediately introduces batch capabilities with 'Supports batch operations via the 'ids' parameter.' It clearly states it deletes one or more trust boundaries, distinguishing it from other delete tools (e.g., delete_trust_zone, delete_crossing_point) by targeting the correct entity.
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 single-item vs batch usage instructions ('For single item: provide the id directly. For batch: provide a list of IDs in the 'ids' parameter.'), giving the agent explicit direction on how to invoke each mode. However, it does not mention alternatives like clear_trust_boundaries for bulk deletion or update_trust_boundary for modification, so the exclusion guidance is absent.
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 present, the description carries the full transparency burden. It discloses the output format (markdown-formatted guide), the content scope (step-by-step guidance), and even mentions logging/error handling via the ctx context. It does not state it is side-effect-free, but the read-only nature is self-evident from 'returns a guide'.
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 concise with a strong lead sentence naming the phase, followed by a brief elaboration of contents. The Args/Returns sections are somewhat formulaic but not bloated; every sentence adds some useful detail, though the misstated Args section could be removed.
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 informational tool with no parameters and an existing output schema, the description covers the purpose, what the guide includes, and the return format. It does not mention prerequisites or 'when in the workflow' to call it, but given the low complexity and the fact that the phase number is baked into the title and first sentence, the description is sufficiently 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 input schema has zero properties, yet the description lists an 'Args: ctx' parameter, which is misleading and contradicts the schema. An agent reading the description might try to pass a context argument that the tool does not accept, so the description actively harms parameter understanding instead of adding 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 tool provides detailed guidance for Phase 5: Asset Flow Analysis, listing concrete contents (objectives, steps, tools, expected outputs). This makes the purpose unmistakable and differentiates it from sibling phase-guidance tools by naming the specific phase.
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 implies the tool should be used when Phase 5 guidance is needed, but it does not explicitly state when to use it vs. other get_phase_X_guidance tools or the main threat modeling plan. No alternatives or exclusions are mentioned, so the usage context is only implied.
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 burden. It discloses that the tool lists assets and returns a markdown-formatted list, which is useful. However, it does not mention authentication requirements, sorting, pagination, or potential errors, leaving some behavioral transparency gaps.
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 reasonably compact but redundant: the first sentence 'List all assets in the system.' is repeated almost verbatim by 'This tool lists all assets in the system...' This duplication could be removed to improve clarity without losing 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?
For a simple list tool with two optional parameters and an output schema, the description is mostly complete. It explains the operation, filters, and return format. It could mention combined filter behavior or result ordering, but those are minor gaps for this complexity level.
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 0%, but the description compensates by explaining both parameters: 'Optional type to filter assets' and 'Optional classification to filter assets.' This adds meaning beyond the schema's bare string/null definitions, though it does not provide possible values or examples.
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 all assets in the system.' It clearly distinguishes from sibling tools like list_components, list_data_stores, and list_flows by naming the exact resource (assets). The optional filters further clarify scope.
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 states the tool can be optionally filtered by type or classification, giving implied context for when to use it. However, it does not explicitly mention alternatives or conditions for when not to use it, unlike examples that name sibling tools.
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 transparency burden. It discloses the return format ('A markdown-formatted list of components') and mentions error handling via ctx, but it does not explicitly state that the operation is read-only or describe any side effects. For a simple list tool, the read-only behavior is implied, but the description could add more explicit context.
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 first sentence is clear and front-loaded, but the second sentence ('This tool lists all components in the system architecture.') is redundant. The Args and Returns sections also mostly duplicate schema information. It is somewhat verbose for a simple tool, but still concise 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?
The description is complete for a simple list tool: it specifies the action, optional filter, and return format. The output schema exists and the single parameter is fully described in the schema. It could mention what happens when no components exist or how the type filter behaves, but these are minor gaps given the tool's simplicity.
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 100%, and the description's Args section simply repeats the schema's 'Optional type to filter components' without adding new meaning. Since the schema fully documents the parameter, the description provides no additional semantic value beyond confirming the optionality.
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: 'List all components in the architecture.' This uses a specific verb (list) and resource (components), and the optional type filter further clarifies scope. It distinguishes itself from sibling list tools like list_data_stores or list_connections by the 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 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 the tool: listing all components in the system architecture, with an optional type filter. It does not explicitly mention alternatives or exclusions, but the resource-specific name and description make the intended usage unambiguous.
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 disclosing behavior. It reveals the return format (markdown) and the filter capability, but does not explicitly state that the tool is read-only or has no side effects. The verb 'list' strongly implies safety, but a more explicit statement about behavior would strengthen transparency.
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 the key purpose, but contains redundancy: 'List all connections in the architecture.' and 'This tool lists all connections in the system architecture.' say the same thing. The Args/Returns structure is useful, but the repetition wastes 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?
Given the tool's simplicity (one optional parameter, output schema present), the description is adequate. It identifies the resource, the filter, and the response format. It does not explain connection structure or fields, but that is presumably covered by the output schema. Minor gap: no mention of ordering or pagination, but not critical for a list 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?
The input schema fully documents the only parameter (component_id) with a description that matches the description text. The description adds no new meaning for that parameter, though it does mention the ctx argument for logging/error handling, which is not part of the schema. With 100% schema coverage, a baseline 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 lists all connections in the architecture, using a specific verb and resource. This distinguishes it from sibling tools like list_components and list_data_stores, which cover different entity types.
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: it lists all connections, with an optional component_id filter. It does not explicitly mention alternatives, but the resource-specific naming and filter parameter imply when to use this tool. No exclusions or edge cases are given, but the scope is unambiguous.
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?
Annotations are absent, so the description must carry the full burden. It does disclose that the tool updates the threat model, indicating a mutating operation. Yet it leaves critical details vague, such as exactly what 'update accordingly' entails, prerequisites, reversibility, and the ambiguous 'Returns: Simple instruction for autonomous threat-specific analysis'. This is incomplete 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized with Args/Returns sections, but the first two sentences are redundant, repeating the same core idea. The 'Returns' line is cryptic and adds confusion rather than clarity. It is not as concise as it could be, though not excessively long.
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 complexity of threat modeling and the absence of annotations, the description leaves significant gaps. It does not clarify what 'update the threat model accordingly' means in practice, what the returned 'simple instruction' is for, or how the code analysis is performed. The output schema exists but is not described, and the tool's side effects are not fully 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 description coverage is 0%, so the description must compensate. It explains code_directory and threat_ids meaningfully, adding value beyond the raw schema. However, it also lists 'ctx' as an argument, which is not in the schema, and the explanation of threat_ids is minimal, 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 clearly states the action ('Check if specific threats are remediated in code') and the resource ('specific threats', 'codebase'), and also indicates it updates the threat model. It distinguishes itself from sibling validation tools like validate_threat_model_against_code by targeting specific threat IDs and explicitly updating the 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?
The description implies when to use the tool: 'Given specific threat IDs' and 'analyze the codebase' provides clear context for targeted remediation validation. However, it does not explicitly mention alternatives or when not to use it, missing the strong exclusion language seen in higher-scoring examples.
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, the description carries the behavioral disclosure burden. It discloses that this is a mutation operation, supports batch operations, and returns a confirmation message with IDs. However, it includes a 'ctx' parameter in the args list that is not present in the schema, and it claims 'content' is required for single item mode while the schema marks it optional with a null default. These inconsistencies muddy the behavioral expectations.
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 structured with an intro, usage instructions, arg list, and return value, but it contains redundancy: 'Add a new mitigation to the model' is repeated in the first line and second paragraph. The inclusion of 'ctx' in the Args list, which is not part of the input schema, adds unnecessary clutter. Overall it is readable but not as tight as it could be.
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?
For a tool with 8 parameters and batch capabilities, the description provides the basic usage and return value but lacks details on the schema of items in batch mode, potential validation rules, and error handling. It doesn't explicitly mention whether mitigations must be linked to threats or if any prerequisites exist. Given the lack of annotations and output schema, a more complete description would be expected.
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 has 0% description coverage, so the description must compensate. It lists all 8 parameters with brief explanations, including the crucial 'items' parameter for batch operations. It also adds constraints like 'content is required for single item mode'. Though some descriptions are vague (e.g., 'Type of the mitigation'), the description provides meaningful semantics beyond the bare 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 it 'Adds one or more mitigations to the threat model' using a specific verb and resource. It distinguishes itself from sibling tools like update_mitigation and delete_mitigation by focusing on the creation aspect and explicitly mentioning batch support.
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 single item vs batch mode: 'For single item: provide content and optional fields directly. For batch: provide a list of mitigation dicts in the items parameter.' This is clear usage context, though it doesn't explicitly mention alternatives or 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.
- Behavior3/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 adds useful details about batch operations and single/batch behavior, but does not mention irreversibility, permissions, or side effects like orphaned components. The return value is noted, but the destructive nature is only implied by the verb 'delete.'
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 brief summary, usage instructions, and argument/return sections. It is slightly redundant, repeating batch info in the first sentence and the following paragraph, but overall it is efficient and front-loaded with the core purpose.
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 simple delete operation, the description covers the main functionality: single and batch deletion, parameter handling, and return type. It does not delve into prerequisites or error cases, but the output schema and complete parameter schema compensate. The description is adequate for a straightforward delete 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 100%, and the description largely restates the schema's parameter descriptions. It does add some value by clarifying the single-vs-batch usage and that 'ids' ignores 'id', but the schema already documents this. Thus the description contributes minimal additional parameter meaning beyond the baseline.
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 'Delete a trust zone' and 'deletes one or more trust zones from the system architecture.' The verb-resource pairing is specific and the batch operation detail distinguishes it from other delete_* tools that lack batch support.
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 using the tool, explaining single-item vs batch modes and how to provide parameters. It does not explicitly mention alternatives or when not to use it, but the resource type makes it obvious which sibling is relevant. No exclusions are stated.
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 burden. It discloses the side effect of saving to a .threatmodel directory and enumerates the content collected. However, it doesn't mention file overwrite behavior, directory creation, or whether the operation is destructive, which are relevant for a filesystem-writing 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 a clear top-line purpose, a bulleted list of included items, and an Args section. It's efficient, though the Args section partly restates the schema, adding modest 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?
For a comprehensive export tool with an output schema, the description covers the main scope, output location, and return summary. It could mention error conditions or exact return format, but the output schema likely 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 description coverage is 0%, so the description compensates. It explains output_path saves in .threatmodel directory and include_extended_data controls extended data beyond standard format, adding some meaning. But it doesn't detail what extended data includes or how the path is resolved.
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 exports a comprehensive threat model to Threat Composer JSON format, with a specific verb (export), resource (threat model), and distinguishing qualifier (comprehensive, all global variables). This differentiates it from sibling export tools like export_threat_model_with_remediation_status.
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 when to use this tool: when a complete threat model with all global variables is needed, as it collects every phase's data. It doesn't explicitly mention alternatives, but the 'comprehensive' scope provides 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of disclosing behavior. It does state the return format ('markdown-formatted guide'), which is useful, but it does not explicitly state that the tool is non-mutating or describe error/authorization behavior. For a read-only getter this is acceptable but not fully 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 front-loaded and compact, with a clear first sentence and concise Args/Returns sections. It has minor redundancy between 'Get detailed guidance' and 'This tool provides step-by-step guidance,' but overall every section serves a purpose.
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 zero-parameter, output-schema-backed informational tool, the description adequately covers purpose, content, and return format. It does not explicitly state usage context or state-safety, but given the tool's simplicity and sibling context, this is sufficient.
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?
There are zero schema parameters, so the baseline is 4. The description's mention of 'ctx' as an argument is somewhat inconsistent with the empty input schema, but it does not need to add meaning for user-facing parameters since none exist.
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 ('Get detailed guidance') and clearly names the resource ('Phase 2: Architecture Analysis'), listing the guide's content (objectives, steps, tools, expected outputs). It distinguishes this tool from sibling phase guidance tools by explicitly identifying Phase 2.
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 what the guide covers but does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternative tools. Usage is implied by the 'Phase 2' name and the sibling set of phase guidance tools.
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 burden. It mentions returning a markdown guide and the purpose, but it does not explicitly state that the tool is read-only or has no side effects. However, given its nature as a guidance retrieval, the absence of side effect disclosure is understandable.
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 concise and well-structured, with a clear purpose statement and breakdown of what the guide includes. The Args/Returns sections add a little noise but are not excessive.
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 detail for a simple zero-parameter guidance tool. It lists the content areas (objectives, steps, tools, expected outputs) and the return format. It could mention the context in which to use the phase, but the name already conveys Phase 6.
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?
There are zero parameters in the schema, so the baseline is 4. The description's mention of a 'ctx' argument in the docstring is not reflected in the schema, but since the tool takes no user-facing parameters, there is nothing additional to explain.
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 detailed guidance for Phase 6: Threat Identification.' It uses a specific verb ('get') and names the exact resource (Phase 6 guidance), which distinguishes it from sibling phase guidance tools for other phases.
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 implies the tool is for Phase 6 guidance but does not explicitly say when to use it versus alternatives like other phase guidance tools. No exclusion criteria or context is provided, though the phase is clear from the name.
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 disclosure burden. It does reveal the auto-validation behavior ('automatically run the threat model validation against the code') and return format, but it does not clarify whether the tool is read-only, potential side effects of validation, or error handling. The description offers some context but lacks completeness.
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 structured with sections (intro, Args, Returns), but the opening sentence 'Get a comprehensive threat modeling plan' is redundant with the tool name. A more concise phrasing would improve it. Still, the format is organized and readable.
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 is largely complete for a planning tool: it specifies the output format, mentions auto-validation, and documents parameters. However, it does not explicitly state when to use this vs. phase-specific guidance, and the ctx parameter is mentioned in Args but absent from the input schema, which could cause confusion. Overall, it provides sufficient context for invocation.
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?
Schema coverage is 0%, so the description compensates effectively. It explains each parameter: 'directory: Directory to check for code files' and 'auto_validate_code: Whether to automatically validate against code.' This adds meaningful semantic detail beyond the bare schema types and defaults.
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 detailed threat modeling plan in markdown format, covering all phases of the threat modeling process.' This specifies the verb (get/returns), resource (threat modeling plan), and scope (comprehensive, all phases), which distinguishes it from sibling tools like get_phase_1_guidance or get_architecture_analysis_plan.
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 implies usage by presenting it as the comprehensive planning tool, but it does not explicitly state when to use it versus alternatives, nor does it provide exclusions or prerequisites. The mention of 'covering all phases' hints at its role, but explicit guidance is absent.
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 burden. It mentions the markdown-formatted return and optional filter, but doesn't explicitly state it's read-only or side-effect-free. The 'list' name implies this, but explicit disclosure would be better.
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 has a clear structure (summary, args, returns) but repeats the same statement in the first two sentences. It's compact overall, with only minor 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 simple list tool with one optional parameter and an output schema, the description adequately covers the essentials: what it lists, the optional filter, and the response format. It doesn't need to explain return values further since output schema exists.
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 only parameter 'type' is fully described in the schema with the same wording as in the description. Since schema coverage is 100%, the description adds no new meaning, meeting the baseline for 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 'List all data stores in the architecture' with a specific verb and resource. It distinguishes itself from add/update/delete data store tools, and the scope 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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool's purpose as a list/read operation is clear, and the optional type filter provides context for narrowing results. It doesn't explicitly mention alternatives, but for a simple listing tool this is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/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 side effects, but it only mentions that it returns 'a confirmation message.' It does not disclose whether updates are partial or full replacement, whether validation occurs, permission requirements, or what happens if an asset does not exist. This is a significant gap 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 well-organized with a summary, mode explanation, Args block, and Returns line. While the opening sentences are somewhat repetitive, the overall structure is front-loaded and each section serves a purpose. It is appropriately sized for an 11-parameter tool.
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 11 parameters and two modes, the description adequately covers the purpose, parameter meaning, and return value. It lacks examples and error handling details, but the presence of an output schema and the clear mode guidance make it sufficient for typical 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 Args section lists all 11 schema properties with brief semantic descriptions (e.g., 'New name of the asset'), fully compensating for the 0% schema description coverage. It also explains the interaction between 'id' (required for single mode) and 'items' (batch mode), which is critical for 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 opens with 'Update an existing asset' and 'Supports batch operations via the items parameter,' clearly identifying the verb, resource, and scope. It distinguishes from siblings like add_asset, delete_asset, and other update_* tools by targeting assets specifically. The dual-mode (single/batch) detail further clarifies what the operation encompasses.
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 explicit instructions for when to use each mode: 'For single item: provide id and fields to update directly' and 'For batch: provide a list of asset dicts in the items parameter.' It does not explicitly contrast with alternatives (e.g., add_asset), but the asset-specific naming and mode guidance make the usage context clear.
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 transparency burden. It discloses that the tool mutates existing crossing points and returns a confirmation message, and it describes batch behavior. However, it omits permission requirements, error cases, reversibility, and effects on related architectural entities, leaving notable gaps 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 well-structured with a front-loaded summary, single/batch mode instructions, an Args block, and a return note. It is somewhat redundant—the second sentence paraphrases the first, and the Args block repeats schema content—but it remains scannable and appropriately sized for a 7-parameter tool.
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 full schema coverage, an output schema, and a clear return description, the description is largely complete for invoking the tool. It covers both usage modes and parameter requirements. Some ambiguity remains around precedence when both id and items are provided, and the description mentions a ctx argument not present in the input schema, but the schema itself covers these 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?
The input schema already provides 100% parameter descriptions, so the baseline is 3. The description reinforces the single-item id requirement and the batch items structure, adding minor mode context, but it largely duplicates the schema's own parameter descriptions without adding significant new 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 'Update an existing crossing point,' a specific verb+resource pairing that clearly identifies the tool's function. It also highlights batch support, which distinguishes it from sibling tools like add_crossing_point, list_crossing_points, get_crossing_point, and delete_crossing_point.
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 explains single-item versus batch usage modes, including the id requirement for single updates and the items structure for batch operations. It does not explicitly mention when not to use this tool in favor of another, but the update-specific context and mode guidance provide sufficient operational clarity.
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 discloses the two operating modes and the return value ('A confirmation message with the connection ID(s)'), but it does not mention side effects, validation, error handling, or duplicate behavior. This is adequate but has clear gaps.
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 a clear summary, but it repeats the same idea in the first two sentences ('Add a new connection...' and 'This tool adds one or more connections...'). The Args section duplicates schema parameter descriptions, adding redundancy. It is not overly long, but every sentence does not earn 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?
For a 7-parameter tool with no annotations and an output schema, the description covers the core purpose, usage modes, and return type. It lacks edge-case context such as duplicate handling or validation behavior, but overall it provides enough information for an agent to select and 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 100%, so the baseline is 3. The description adds value by explicitly explaining the single vs batch interaction model, including that source_id and destination_id are required for single mode and that items contains a list of connection dicts. This clarifies relationships beyond individual schema 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 'Add a new connection to the architecture' and 'adds one or more connections between components in the system architecture,' using a specific verb and resource. It distinguishes from sibling tools like update_connection and delete_connection by focusing on creation and explicitly mentioning batch mode.
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 guidance on when to use single vs batch mode: 'For single item: provide source_id, destination_id, and optional fields directly' and 'For batch: provide a list of connection dicts in the items parameter.' This gives actionable context, though it does not explicitly mention alternative tools or when not 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.
- Behavior3/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 states the action and return value, but does not discuss error handling, idempotency, or effects on existing connections. This is adequate for a simple add but lacks deeper edge-case transparency.
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 includes a formal Args block that largely duplicates schema descriptions and even lists a 'ctx' parameter not present in the schema. While organized, it could be more concise without losing key mode explanations.
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 three parameters and an output schema, the description covers single and batch usage, parameter roles, and return value. It does not mention edge cases or relationships to sibling tools, but overall it provides enough context 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 100%, so baseline is 3. The description adds value by clarifying the mode-dependent semantics: which parameters are required for single items, and that 'items' overrides individual parameters. This goes beyond the schema's per-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 verb+resource: 'Add a connection to a crossing point.' This clearly distinguishes it from sibling tools like add_connection and add_crossing_point, and the rest of the description reinforces the two operating modes.
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 explains when to use single vs batch mode, including that 'items' ignores individual parameters. However, it does not compare against alternatives like remove_conn_from_crossing or add_connection, leaving some usage context implicit.
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 discloses the batch behavior (adding one or more data stores) and the return format (confirmation with ID(s)). It also notes that the 'items' parameter enables batch operation, which is useful beyond the schema. It does not detail edge cases like duplicate name handling, but for a create operation it is reasonably transparent.
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 well-structured with a summary, mode explanations, an args list, and a returns line. However, the Args list largely repeats the schema descriptions, making it longer than necessary. It is not overly verbose, but the redundancy prevents a higher score.
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 has 7 parameters, a batch mode, and an output schema. The description explains the two modes, the required fields for single-item mode, the batch structure, and the return value. It is sufficiently complete for effective use, though it could mention possible error conditions, but the output schema likely covers return 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 100%, so the schema already documents all parameters. The description adds some context by distinguishing single-item parameters from the batch 'items' parameter and mentioning the 'ctx' parameter (not in schema), but most of the Args section duplicates schema descriptions. The added value over the schema is marginal.
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: 'Add a new data store to the architecture' and clarifies it also supports batch operations via the 'items' parameter. This clearly distinguishes it from sibling tools like update_data_store and delete_data_store, and from add_component/add_connection which target other architecture elements.
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 single-item mode versus batch mode, with explicit instructions for each. It does not explicitly name alternatives or exclusion criteria (e.g., when to use update_data_store instead), but the usage context is well-defined and unambiguous.
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 of behavioral disclosure. It indicates this is an analytical operation returning markdown, which implies no modification, but it does not explicitly state side effects, prerequisites like existing threat actors, or error behavior.
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 short and front-loaded with the core action and output format. There is minor redundancy between 'Analyze the threat actors.' and the immediately following sentence, but the Args/Returns structure keeps it 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?
For a zero-parameter analysis tool, the core behavior and markdown return are stated, and an output schema exists to define return details. However, it lacks when-to-use guidance, an explicit non-mutating guarantee, and prerequisites, so it is not fully 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 input schema has zero parameters, so the baseline is 4. The description adds the ctx MCP context for logging and error handling, which is not in the schema, and no other parameter semantics are needed.
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 'Analyze' plus resource 'threat actors' and explicitly states it provides recommendations, clearly distinguishing it from sibling CRUD tools like list_threat_actors and get_threat_actor.
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 states the tool 'analyzes the threat actors in the threat model and provides recommendations,' giving clear context for when to use it. It does not explicitly mention when not to use it or list alternatives, which would merit a 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?
With no annotations, the description carries the full burden for behavioral disclosure. It clearly states the destructive action ('clears all components, connections, and data stores'), but does not explicitly warn about irreversibility or potential side effects on related entities like threats or trust boundaries. A bit more caution language would improve 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?
The description is appropriately concise, with a one-line summary, a clear scope statement, and a returns note. Every sentence earns its place without 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?
Given the tool has zero parameters and an output schema, the description is fairly complete: it states the action, the exact scope, and the return type. However, it lacks an explicit caution about the destructive nature or any impact on related architecture elements, which would make it more complete for agent decision-making.
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 has zero parameters, so the baseline is 4. The description mentions an 'Args: ctx' parameter not present in the schema, which is a standard MCP context object and not a user-facing parameter, so it doesn't mislead significantly. No additional parameter explanation needed.
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's purpose with a specific verb ('clears') and resource ('architecture'), and explicitly enumerates what gets cleared (components, connections, data stores). This distinguishes it from sibling clear tools like clear_business_context and clear_threat_actors.
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 implies usage by naming the scope (all components, connections, data stores), but provides no explicit when-to-use/when-not-to-use guidance or alternatives. It's clear this is for resetting the architecture, but no contextual preconditions or exclusions are mentioned.
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, the description carries the transparency burden. It discloses the destructive nature, batch support, and confirmation return, but does not mention side effects, reversibility, or prerequisites. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably structured with Args/Returns, but the opening two sentences are redundant ('Delete a mitigation from the model' and 'This tool deletes one or more mitigations from the threat model'). Could be tightened 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?
For a two-parameter delete tool with an output schema, the description covers the key usage modes and return type. It does not discuss errors or edge cases, but the tool is simple enough that this is not a major 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?
Schema description coverage is 0%, so the description must compensate. It explains that 'id' is for single-item mode and 'ids' for batch, and clarifies that 'id' is required in single mode, adding meaning beyond the bare schema properties.
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 it deletes a mitigation from the model, specifying the exact resource and operation. It distinguishes from sibling delete_* tools by explicitly naming 'mitigation' and '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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage context for single versus batch deletion via the 'id' and 'ids' parameters. It does not explicitly exclude alternatives or mention when not to use, but the single/batch guidance is actionable and specific.
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 discloses that the return is a markdown-formatted description, which is useful. It does not explicitly state read-only behavior or error handling for missing IDs, but these are implied for a getter. The mention of a non-schema 'ctx' argument adds minor confusion, slightly reducing 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 concise and well-structured with a one-line summary, Args, and Returns sections. The id description is redundant with the schema, and the ctx line is unnecessary, adding minor bloat. Still, it is front-loaded with the main purpose and reads clearly.
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 getter with one parameter and an output schema, the description is mostly complete. It states the purpose, the parameter, and the return format. It does not explain error scenarios or how to obtain IDs, but these are adequately covered by sibling tools like list_assumptions. The output schema further covers 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?
The schema already documents the only parameter, id, with the exact same description. The description adds no new semantic information for id. Worse, it lists 'ctx' as an argument, which is not present in the schema, potentially misleading the agent into passing an unsupported parameter. This confusion outweighs the neutral baseline from 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 opens with a clear verb-object statement: 'Get details about a specific assumption.' This unambiguously identifies a retrieval operation for a single assumption, distinguishing it from siblings like list_assumptions (list all) and add/update/delete operations. The return format is also mentioned, further clarifying the purpose.
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 phrase 'specific assumption' implies the tool is for retrieving a single item by ID, which is clear context for when to use it. However, it does not explicitly mention alternatives like list_assumptions for finding IDs or update_assumption for modifying. For a simple CRUD getter, this is acceptable but not fully explicit.
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 must carry the burden of behavioral disclosure. It does state that the tool lists assumptions and returns a markdown-formatted list, and it mentions the ctx parameter for logging/error handling. However, it does not explicitly disclose whether this is a read-only operation or describe behavior like ordering, pagination, or errors. For a simple list tool, this is minimally adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence purpose, followed by clear Args and Returns sections. Every sentence serves a purpose, with 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 with one optional parameter and an output schema (per the context signal), the description is complete enough. It explains what the tool does, the filter, and the return format. It could mention read-only behavior or pagination, but these are not critical given the simplicity.
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 100% for the single 'category' parameter, so the schema already fully documents it. The description adds the phrase 'filter assumptions' and specifies the context parameter (ctx), but this is not a major addition beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('list'), resource ('assumptions'), and scope ('in the threat model'), and clearly distinguishes itself from sibling tools like get_assumption (which retrieves a single assumption) and add/update/delete operations. The optional category filter is also mentioned, making the tool's exact function 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 implies when to use the tool: when you need all assumptions rather than a single one, and optionally filter by category. Although it does not explicitly name alternatives or exclusions, the contrast with get_assumption and the 'all' phrasing provide clear context for the appropriate use case.
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 burden. It clearly indicates a read-only operation via the verb 'list' and states the return format as a markdown list. However, it does not disclose potential behaviors like result ordering, pagination, or performance implications, though these are less critical for a simple 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise, but the first two sentences are redundant: 'List all asset flows in the system.' is repeated with 'This tool lists all asset flows in the system...' The Args/Returns structure is helpful, but the redundancy makes it less crisp than it could be.
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 with optional filters and an output schema, the description covers the essential aspects: purpose, parameters, and return format. It lacks details like pagination or default behavior when no filters are provided, but these are not critical for this type of 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 0%, so the description compensates well by explaining both parameters as filters. It adds meaning to asset_id and component_id. The inclusion of 'ctx' in the Args section is not present in the schema, which could be slightly confusing, but it is clearly labeled as MCP 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 function with a specific verb ('List') and resource ('asset flows'), and distinguishes it from sibling tools like list_assets or list_components. The optional filters are mentioned upfront, 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: to list asset flows, optionally filtered. However, it does not explicitly state when to use this tool versus alternatives (e.g., get_flow for a single flow) or provide any exclusions. The context is clear but not fully elaborated.
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 must carry the full burden. It discloses the batch update behavior, the requirement for 'id' in batch items, and that a confirmation is returned. However, it does not clarify whether updates are partial or full replacement, how missing fields are handled, or any side effects on related architecture elements.
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 organized and front-loaded with the purpose, but the first two sentences are redundant ('Update an existing data store' and 'This tool updates one or more existing data stores'). The Args list is necessary but lengthy, making it slightly less concise than it could be.
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 CRUD tool with eight parameters and a provided output schema, the description covers the essential aspects: single/batch modes, parameter semantics, and the return type. It does not explain deletion or creation, but those are covered by sibling tools. Sufficient for an agent to effectively use 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 covers 100% of parameters, and the description adds the crucial single/batch mode distinction, including that 'id' is required for single mode (which the schema's 'required' list misses). It also clarifies the structure of 'items' entries, adding value 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?
States explicitly that it updates an existing data store, with the verb 'update' and resource 'data store'. Distinguishes from siblings like add_data_store, list_data_stores, and delete_data_store by emphasizing modification of existing entities. Also highlights batch support.
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 instructions for when to use single vs. batch mode, including that 'items' overrides individual parameters. Does not explicitly mention when not to use (e.g., for creating new data stores, use add_data_store), but the sibling list makes that implicit.
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, the description carries the burden of disclosing behavior. It explains the batch capability, the requirement that each batch item include 'id', and that it returns 'A confirmation message.' However, it does not clarify partial-update semantics, validation of field values, or error behavior for invalid IDs, leaving important behavioral aspects undisclosed.
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, Arg list, and Returns section. It is slightly redundant (the first and second paragraphs restate the same purpose), and the Args list is long, but it remains organized and easy to scan.
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 main modes, parameters, and return type, but it does not explicitly state that either 'id' (single) or 'items' (batch) must be provided, despite neither being marked required in the schema. It also lacks details on field value constraints and batch item structure beyond requiring 'id,' which leaves gaps for an agent trying 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 0%, so the description must compensate. It adds meaning by explaining the single vs batch modes, marking 'id' as required for single mode, and clarifying that 'items' is an optional list for batch updates. While some field descriptions are minimal ('New content', 'New type'), the mode-specific context provides significant value beyond the raw 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 function: 'Update an existing mitigation' and 'updates one or more existing mitigations in the threat model.' It uses a specific verb and resource, and distinguishes itself from sibling tools like add_mitigation, delete_mitigation, and list_mitigations.
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 operational guidance for both single and batch modes: 'For single item: provide id and fields to update directly' and 'For batch: provide a list of mitigation dicts in the items parameter.' This communicates when to use the tool and how to structure calls, though it does not explicitly contrast with add/delete tools.
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, the description carries the full transparency burden. It discloses batch behavior, the requirement for 'id' in items, and returns a confirmation message. However, it does not detail error handling, partial failures, or whether omitted fields are left unchanged.
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 well-structured but verbose, repeating the schema's parameter documentation in an Args block. The batch vs single guidance is valuable, but the full argument list is redundant with the input schema and could be trimmed.
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 11 parameters and two usage modes, the description covers mode selection, required fields, and the return type. It does not discuss error scenarios or partial update behavior, but an output schema exists and likely covers return 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 100%, so the baseline is 3, but the description adds operational meaning beyond the schema: id is required for single mode, and items must contain 'id'. It also clarifies that individual parameters are ignored when items is provided (partially stated in 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 uses a specific verb ('Update') and resource ('threat actor'), and clearly distinguishes single vs batch operations. This separates it from sibling tools like add_threat_actor, delete_threat_actor, list_threat_actors, etc.
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 explicitly explains two usage modes: single item (provide id and fields) and batch (provide items list with id). It also notes that each batch item must include 'id'. However, it does not mention alternatives like set_threat_actor_relevance or set_threat_actor_priority for field-specific updates.
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, the description carries the full burden. It discloses useful behavior such as batch support and that "When provided, individual parameters are ignored." However, it does not mention failure modes, error handling, permission requirements, or side effects on related entities. The return type is only vaguely described as "A confirmation message".
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 the main purpose and structured into Args and Returns sections. However, there is redundancy: the first sentence says 'Update an existing trust zone' and the next paragraph repeats 'This tool updates one or more existing trust zones'. It could be tightened to eliminate the 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?
The tool has moderate complexity with 5 parameters and batch support. The description explains both operating modes, parameter semantics, and (with an output schema present) the return type. It lacks details on validation or error conditions, but for an update tool, the provided information is largely sufficient.
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 100% for all parameters. The description adds value beyond the schema by clarifying that 'id' is required only in single-item mode and that 'items'' takes precedence over individual parameters. The inclusion of 'ctx' in the Args list, though absent from the schema, might confuse but does not detract from the overall clarity.
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: "Update an existing trust zone" and explicitly mentions batch support, which distinguishes it from other update tools for different entities (e.g., update_component, update_connection). It names the specific resource (trust zone) and the operation (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?
The description provides explicit usage modes: "For single item: provide id and fields to update directly. For batch: provide a list of trust zone dicts in the 'items' parameter." It implies this tool is for updating existing zones (not creating or deleting), but does not name alternative tools or explicitly state 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?
Without annotations, the description must disclose behavioral details. It states the tool returns 'a clear message indicating whether the business context is complete or what features are still missing,' which clarifies the output behavior. However, it does not disclose whether the operation is read-only, whether it has side effects (like logging), or any prerequisites beyond the phase context. The mention of 'ctx: MCP context for logging and error handling' hints at possible logging, but it's not explicit.
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 an initial purpose sentence, then a validation message explanation, and a docstring-like Args/Returns section. It is front-loaded and every sentence adds context. 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?
Given zero parameters and an output schema that presumably describes the return value, the description adequately covers the tool's function and usage timing. It mentions validation before the next phase, which ties it to the phase-based workflow. It could be improved by mentioning what to do if validation fails (e.g., use set_business_context), but that's not strictly necessary.
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 zero properties, so there are no user-facing parameters to describe. The description's 'Args: ctx' section is technically misleading because `ctx` is not in the schema; it appears to be an internal context parameter. Since the schema covers 100% of parameters (none), the description adds no helpful parameter semantics and could confuse the agent about whether to pass `ctx`.
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: 'Validate that all business context features are set before proceeding to next phase.' This distinguishes it from sibling tools like set_business_context or get_business_context_features by focusing on completeness validation. The verb 'validate' and resource 'business context features' 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 specifies when to use the tool: 'before proceeding to next phase,' which is a clear trigger context. However, it does not explicitly mention alternatives or when not to use it, such as 'use get_business_context to inspect values' or mention that this is a gate check before advance_phase. So it provides context but no exclusions.
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. It discloses that the tool adds one or more trust zones and returns a confirmation with ID(s), which implies a write operation. However, it does not disclose behavioral details like what happens on duplicate names, whether batch operations are atomic, any permission requirements, or side effects on existing architecture. The statement 'individual parameters are ignored' when items is provided is only in schema, not in the description, and the description's Args section mentions 'ctx' which is not part of the schema, adding slight confusion.
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: it starts with the core purpose, then explains single vs batch modes, followed by an Args list and Returns. The inclusion of 'ctx' in Args is slightly extraneous since it's not in the schema, but overall it is appropriately sized and every sentence contributes 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 complexity of batch support and the presence of an output schema, the description covers the main usage modes, required field nuances, and return value. It does not cover edge cases like partial batch failures or duplicate handling, but the combination of schema coverage, output schema, and description is sufficient for an agent to invoke the tool correctly for standard operations.
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 100%, so the schema already documents each parameter. The description adds meaningful semantics by clarifying that 'name' and 'trust_level' are required for single item mode, and that 'items' is a list of dicts each containing 'name', 'trust_level', and optionally 'description'. This explains the mode-dependent behavior beyond the schema's simple 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 the tool 'Adds a new trust zone' and explicitly supports batch operations via the 'items' parameter, distinguishing it from sibling tools that add other resources (e.g., add_component, add_data_store) and from update/list/delete trust zone tools. The verb 'add' is specific and the resource 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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains two usage modes: single item (providing name, trust_level, and optional fields) and batch (providing a list of dicts in 'items'). This gives clear context for how to invoke the tool. However, it does not explicitly mention alternatives or exclusions, such as 'use update_trust_zone for existing zones' or 'avoid this if you need to modify existing trust zones'.
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, the description carries the full burden. It discloses that the operation is a retrieval and that the result is markdown-formatted, which adds some value. However, it does not state whether there are side effects, error behavior, or permissions needed.
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 relatively concise and well-structured with Args/Returns sections. There is minor redundancy between the first sentence and the second sentence, but overall it is efficient and front-loaded.
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 single-parameter retrieval tool, the description covers the purpose, the parameter, and the return format. The presence of an output schema reduces the need to explain return values. It is adequate, though it omits error 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 description coverage is 0%, so the description must compensate. It explains that 'id' is the ID of the mitigation to retrieve, which adds meaning beyond the raw schema. It also mentions 'ctx' for logging, though this is implementation detail.
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 retrieves details about a specific mitigation, using a specific verb and resource. It distinguishes itself from sibling tools like list_mitigations, add_mitigation, and delete_mitigation by focusing on a single entity by ID.
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 context is clear: use this when you need details for a specific mitigation. However, it does not explicitly mention alternatives like list_mitigations or provide exclusions, 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.
- 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 transparently explains the tool returns a markdown-formatted guide and lists the content (objectives, steps, tools to use, expected outputs). It does not mention side effects, which is acceptable for a read-only retrieval 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 an overview and a documentation-style Args/Returns section. It is somewhat verbose for a tool with no parameters, but remains concise and front-loaded with the primary purpose.
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 simplicity (no input parameters, static guidance retrieval), the description sufficiently covers the output format and content. The existence of an output schema further reduces the need to explain return values. It is complete for its intended use.
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 has zero parameters, so the baseline is 4. The description mentions a 'ctx' argument, but it is not in the schema. This is not contradictory and adds slight context about the implementation, but does not harm semantic clarity.
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 detailed guidance for Phase 4: Trust Boundary Analysis' with a specific verb and resource. It distinguishes itself from sibling tools by phase number (Phase 4) and topic, unlike generic phase guidance tools.
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 implies the tool is used when you need step-by-step guidance for trust boundary analysis, but it does not explicitly state when to use it versus other phase guidance tools or alternatives. It lacks exclusionary or alternative recommendations.
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 explains that the tool provides step-by-step guidance, includes conditional next steps based on code detection, and returns a markdown-formatted guide. The directory parameter is described as checking for code files, which indicates a read operation on the directory. This is sufficient for a non-mutating guidance tool, though it could be more explicit about side effects (none expected).
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 concise summary, details section, and clearly labeled Args/Returns blocks. It is not overly verbose, but the inclusion of 'ctx' (not in the schema) adds unnecessary clutter. Overall, every sentence serves a purpose except the ctx mention, which is solid.
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 simplicity and the presence of an output schema, the description is complete. It states what the tool returns (markdown guide with conditional steps), the input parameter, and the conditional behavior. It could be slightly more complete by noting that it only reads the directory and does not modify any state, but for a guidance tool this is adequate.
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 0%, so the description must compensate. It does by explaining the directory parameter: 'Directory to check for code files (default: current directory)'. This adds meaning beyond the schema's bare property definition. However, the description also mentions a 'ctx' argument that is not present in the schema, which could cause confusion, slightly reducing the 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 clearly states the tool's purpose: "Get detailed guidance for Phase 7: Mitigation Planning." It specifies the exact phase and what it provides (objectives, steps, tools, outputs), distinguishing it from sibling guidance tools for other phases. The name and description together leave no ambiguity about the resource being accessed.
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 implies usage by naming the phase and listing the content (step-by-step guidance for mitigation planning), but it does not explicitly state when to use this tool versus the other phase guidance tools or provide alternatives. The conditional note about 'next steps' gives some context, but there is no direct when-to-use or 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the return format (markdown list) and that results can be filtered. However, it doesn't explicitly state that the operation is read-only or non-destructive, though 'list' semantically implies this.
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 reasonably concise, with the main purpose front-loaded. It contains a slight redundancy between the first and second sentences, but the overall structure is clear and each section 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?
For a simple list tool with three optional filters and an output schema, the description is complete enough: it explains the return format, the filtering capability, and parameter semantics. It lacks details like sorting or pagination, but these are likely not essential for this 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 has 0% description coverage, so the description must compensate. It explains each parameter's purpose ('Optional category to filter threats'), which adds meaning beyond the bare names. Enums or value ranges would be richer, but it's 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 clearly states the tool's verb ('list'), resource ('threats'), and scope ('in the model'), and mentions optional filtering. It distinguishes this from sibling list tools (list_mitigations, list_assets, etc.) by naming the specific resource.
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 context: use this tool to list threats with optional filters. It does not explicitly name alternatives or exclusion criteria, but the purpose is unambiguous and implies when 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?
No annotations are provided, so the description carries the full burden. It discloses batch behavior, the requirement for id in single mode, and the return confirmation. However, it does not state whether omitted fields are preserved or overwritten, nor does it describe error behavior for invalid or missing ids.
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 with the core purpose and batch support. It includes a redundant Args list that repeats schema information, but the sectioned format makes it easy to scan. It is slightly verbose but not excessively so.
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 main modes, parameters, and return value. It does not discuss edge cases like what happens if neither id nor items is provided, or if a field must be present. However, the output schema exists, and the tool is moderate in complexity, so the description is largely sufficient.
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 100% of parameters, so the baseline is 3. The description adds value by clarifying that id is required for single item mode and that each batch item must include id, which helps disambiguate usage. It also explains the difference between single and batch parameter handling.
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 'Update an existing assumption' with a specific verb and resource, distinguishing it from sibling tools like add_assumption, list_assumptions, get_assumption, and delete_assumption. It also notes batch support, further clarifying the tool's 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 provides clear context for two usage modes: single item (provide id and fields) and batch (provide items list with ids). It does not explicitly exclude alternatives, but the purpose is distinct enough that an agent can infer when 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, the description carries the burden of disclosing behavior. It does state the return format (markdown-formatted), which is useful, but it omits edge-case behavior such as what happens if no context has been set yet, and it does not explicitly confirm that the operation is read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded. The first sentence states the purpose, followed by a brief explanation and a clear Args/Returns structure. No redundant sentences.
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 zero-parameter getter, the description covers the essential return format and data source. It lacks a note about prerequisites (e.g., needing to set the context first), but given the simple nature and presence of sibling tools, this is a minor 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 has zero parameters, so the baseline is 4. The description does not add user-facing parameter semantics, but it mentions an internal 'ctx' parameter for logging, which is extra context beyond the schema, though potentially confusing if considered a user 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?
The description states a specific verb ('returns') and resource ('business context'), and clarifies the origin ('created from the answers to the clarification questions'). This distinguishes it from siblings like set_business_context or get_business_context_features.
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 this is the retrieval counterpart to set_business_context, with context about the source of the data. However, it does not explicitly state when not to use it or mention alternatives like get_business_context_features, leaving some room for 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 provided, the description carries the burden of behavioral disclosure. It states the return type (markdown-formatted guide) and the content included (objectives, steps, tools, expected outputs), which is sufficient for a read-only guidance retrieval tool. No contradictory or hidden behaviors are indicated.
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 somewhat redundant, repeating 'guidance' and including an Args section for a non-existent schema parameter. It could be condensed to one or two sentences without losing meaning, but it is still reasonably readable.
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 no-parameter tool with an output schema available, the description adequately explains what the tool does and what the returned guide contains. The mention of 'tools to use' and 'expected outputs' gives sufficient context for integrating with the broader phase workflow.
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?
There are zero parameters in the schema, so the 0-param baseline of 4 applies. The description mentions 'ctx' in Args, but since this isn't a schema property, it adds minor noise; however, it doesn't mislead about actual 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 'Get detailed guidance for Phase 9: Output Generation and Documentation' with a specific verb and resource. It distinguishes itself from sibling phase guidance tools by specifying Phase 9 and its focus.
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 usage is for Phase 9 by naming the phase directly. It doesn't explicitly exclude other phases or name alternatives, but the phase-specific context is strong enough for an agent to select it correctly.
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 burden. It discloses single vs batch behavior, that fields are new values, and that a confirmation message is returned. However, it does not discuss error handling, partial failures, idempotency, or whether unspecified fields are left unchanged.
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 summary line and an Args list. The opening is slightly repetitive ('Update an existing asset flow' followed by 'This tool updates...'), but overall it is efficient and front-loaded.
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 (14 params, batch support) and zero annotations, the description provides substantial coverage: modes, parameter meanings, and return type. Gaps include error conditions, required vs optional fields, and concurrency semantics, so it is not fully complete.
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?
Schema description coverage is 0%, but the description compensates fully by listing every parameter with meaningful semantics (e.g., 'New ID of the asset being transferred', 'risk_level (1-5)'). It also clarifies that batch items must include 'id' and that id is required for single mode.
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 updates existing asset flows, using a specific verb and resource. It distinguishes from sibling update tools by naming the resource (asset flow) and explaining both single and batch modes.
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: updating existing asset flows, with explicit mode instructions (single id vs items list). However, it does not explicitly mention when not to use it or reference alternatives like add_flow or update_asset.
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 discloses batch operations, the 200-character limit, and that each batch item must include an id. However, it does not explain behavior for invalid IDs, partial batch failures, or whether omitted fields are left unchanged. It also only promises a 'confirmation message' without detailing its contents.
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 organized with a summary and Args section. Every sentence provides useful information, though it could rely on the schema for parameter names if coverage were higher. Critical operational details are front-loaded.
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 has 13 parameters and batch mode, but the description covers the main modes, the character limit, and batch prerequisites. It omits edge-case behaviors like non-existent IDs, merge semantics, and batch failure handling, but the presence of an output schema reduces the need to describe return values.
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?
Schema description coverage is 0%, so the description must compensate. It provides a detailed Args section describing each parameter's purpose, constraints (e.g., max 200 chars for text fields), and required status (id required in single mode). This adds significant meaning beyond the raw 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 'Update an existing threat' and 'updates one or more existing threats in the threat model,' using a specific verb (update) and resource (threat). It distinguishes from sibling tools like add_threat, delete_threat, list_threats, and get_threat.
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 guidance: 'For single item: provide id and fields to update directly. For batch: provide a list of threat dicts in the items parameter.' Also highlights the 200-character constraint. While it doesn't explicitly mention alternatives, the single/batch instructions clarify when each mode should be used.
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 exist, so the description carries the transparency burden. It discloses conditional parameter requirements (name/type/classification required for single mode), the batch capability, and the return value (confirmation with asset ID(s)). It does not cover permissions, idempotency, or failure behavior, so a 4 is appropriate.
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 with its purpose and mode guidance. The only notable issue is a slight redundancy between 'Add a new asset' in the first sentence and 'This tool adds one or more assets' in the second, which wastes a little space.
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 10 parameters, two usage modes, and output schema, the description covers the essential behavior and return format. It lacks details about the structure of individual items in the batch dict and any prerequisites, but it is sufficient for an agent to invoke the tool correctly in typical 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 description coverage is 0%, so the description is essential. It adds meaningful context by providing examples for type and classification, ranges for sensitivity and criticality, and by clarifying the batch 'items' parameter. Some descriptions like 'Owner of the asset' and 'Description of the asset' are still tautological, preventing a 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 clearly states 'Add a new asset to the system' and elaborates that it supports both single and batch operations. It distinguishes itself from sibling tools like update_asset and list_assets by focusing on creating one or more assets.
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 explicit mode-based usage guidance: for single items provide name, type, and classification directly; for batch use the 'items' parameter. It does not mention when to use this tool over similar add_* tools or when not to use it, so it misses a top score.
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 tool creates one or more components, supports single and batch modes, and returns a confirmation with component ID(s). It does not mention permissions, validation, or overwriting behavior, but for an add tool it is reasonably 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 well-structured with a summary, Args list, and Returns. However, the opening lines are somewhat redundant ('Add a new component' and 'This tool adds one or more components' repeat the same idea), and the Args list largely repeats schema descriptions. Still, it's reasonably concise and 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?
For an 8-parameter tool with two modes, the description provides enough context to invoke it correctly: it explains single vs batch, required fields in single mode, and the return value. It doesn't address edge cases or error handling, but with an output schema available, it is largely 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 already documents all 8 parameters with 100% coverage, so baseline is 3. The description adds value by clarifying that name and type are required for single-item mode (schema has no required fields), and by explaining the batch behavior via items. However, it includes a phantom 'ctx' parameter not present in the schema, which is a minor flaw.
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 'Add a new component to the architecture' and further explains it adds one or more components. The verb 'add' and resource 'component' are explicit, and the batch note distinguishes this from update/delete/list 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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use single-item vs batch mode using the 'items' parameter, providing clear context for both paths. However, it doesn't explicitly mention alternatives like 'use this for creating, not updating components' or exclusions, so it lacks explicit when-not 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 full burden. It discloses batch behavior via the 'items' parameter, notes that items mode ignores individual parameters (in the schema), and states the return value ('confirmation message with the threat actor ID(s)'). It does not cover permissions or duplicate handling, but the core behavioral surface is well described.
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 a short summary, then explains usage modes, parameters, and returns in a structured format. While the Args list duplicates schema descriptions, it is organized logically and each section serves a purpose for the tool's 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?
Given the tool's complexity (10 parameters, batch mode, output schema), the description adequately covers the main usage scenarios, required fields per mode, and return type. It could mention error conditions or validation, but the core completeness is sufficient.
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 100%, so baseline is 3. The description adds value by grouping parameters into single-item vs batch contexts and explicitly marking fields as 'required for single item mode.' This clarifies when each parameter is needed beyond the 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 clearly states the tool's function: 'Add a new threat actor' and 'adds one or more threat actors to the threat model.' It specifies the resource (threat actor) and verb (add), and distinguishes from sibling CRUD tools like update_threat_actor, list_threat_actors, and delete_threat_actor.
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 explicit guidance for two usage modes: single item (provide name, type, capability_level, motivations, resources directly) and batch (use 'items' parameter). While it does not name alternatives like update_threat_actor for modifications, the 'add' semantics and clear mode distinctions give solid 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?
The description discloses the key behavioral constraint that assets cannot be deleted if used in any flows, which is critical for the agent to anticipate failures. It also explains the single/batch modes and the return value as a confirmation message. With no annotations provided, this adds meaningful context beyond the schema, though it doesn't mention irreversibility 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a short summary, mode explanations, and an Args/Returns section. However, it repeats 'Delete an asset from the system' in the first sentence and second paragraph, which is slightly redundant. Overall, it's easy to scan and every substantive point is covered.
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 delete tool, the description covers the essential aspects: purpose, modes, a key dependency constraint, and return type. The presence of an output schema means the vague return statement is acceptable. Minor gaps include not specifying behavior when both id and ids are provided or when neither is provided, but these are edge 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 input schema has 0% description coverage, so the description takes on the burden of explaining parameters. It clearly defines 'id' for single deletion, 'ids' for batch, and 'ctx' for logging. Each parameter's role is clarified, and it specifies the mode in which each is used, adding value over the raw 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 uses the specific verb 'delete' and resource 'asset', clearly distinguishing it from sibling tools like delete_component and delete_flow. It also mentions batch capability, making the tool's full scope 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 clearly states when to use the tool (to delete one or more assets) and explains the two modes (single vs batch). It doesn't explicitly compare to alternatives, but the resource-specific naming and context make the usage 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?
No annotations are present, so the description carries the full burden. It transparently discloses the return format ('markdown-formatted'), content ('prompts for LLM analysis'), and methodology ('AI-powered analysis with AWS documentation validation'), which is sufficient for a read-only plan-generation 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 front-loaded with a clear topic sentence and uses structured Args/Returns sections for additional clarity. It is slightly redundant ('Get...' followed by 'This tool returns...') but remains concise 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 that there are no annotations and no schema parameters, the description adequately conveys purpose, output format, and analysis context. Since an output schema exists, detailed return-value explanation is unnecessary; the description is complete for a zero-parameter plan 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 input schema has zero properties and schema description coverage is 100%, so no parameter explanation is needed. The mention of 'ctx' in Args is not reflected in the schema, but it does not affect user-facing 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 uses the specific verb 'Get' and names the resource clearly: 'comprehensive asset flow analysis plan'. It states the plan is for analyzing asset flows for security concerns, which distinguishes it from sibling analysis-plan tools like get_trust_boundary_analysis_plan.
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 indicates when to use this tool by specifying its purpose: 'for analyzing asset flows for security concerns'. It does not explicitly name alternatives or exclusions, but the asset-flow scope provides clear contextual 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 provided, so the description carries the full burden. It discloses that the tool returns a markdown-formatted guide and outlines the content (objectives, steps, tools, expected outputs). It also mentions logging/error handling via ctx. It does not explicitly state read-only behavior, but this is implied.
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 concise and front-loaded with the main purpose. The Args section is slightly redundant given no schema parameters, but the overall structure is clear and efficient.
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 guidance retrieval tool, the description is complete: it states what the tool does, what it returns, and the content of the guide. It lacks explicit preconditions or read-only guarantees, but these are not critical for this type of 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?
There are zero parameters in the schema, so the baseline is 4. The description mentions 'ctx' as an argument, which is not listed in the schema, but is likely an internal MCP context. Since there are no actual parameters to document, the description adds minimal but acceptable 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 retrieves detailed guidance for Phase 7.5: Code Validation Analysis, using a specific verb (Get) and a well-defined resource. It distinguishes itself from sibling tools like get_phase_7_guidance by specifying the sub-phase.
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 about when to use this tool: when step-by-step guidance for conducting code validation analysis is needed. It does not explicitly mention when not to use it or alternatives, but the intent is clear enough.
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 the mutation of the threat model ('update the threat model accordingly'), the autonomous decision-making expected of the agent, and the return type ('Simple instruction for autonomous analysis'). This goes beyond basic operation description.
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 concise and well-structured: a lead purpose sentence, a context paragraph, and an Args/Returns section. Every part earns its place, though the first two sentences are slightly redundant. 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?
For a complex tool, the description provides a clear high-level workflow: analyze code, compare against threat model, update model, return an instruction. It does not detail the output schema, but since an output schema exists, that is acceptable. It could elaborate on the scope of updates, but overall it is sufficient.
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 provides explanations for both schema parameters: code_directory ('Directory containing code to analyze') and file_patterns ('Optional list of file patterns to include'). It also includes 'ctx' which is not in the schema, creating minor inconsistency, but the key parameters are well-covered despite the 0% schema coverage signal.
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: 'Check what security controls are implemented in code and update threat model.' This clearly states what the tool does and distinguishes it from siblings like 'validate_threat_model_against_code' by emphasizing the update action and autonomous analysis.
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 the tool: 'Given the current threats and mitigations in the threat model, analyze the codebase...' This implies a precondition (existing threat model) and a scenario. However, it does not explicitly mention alternatives or exclusions, which prevents 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?
With no annotations, the description carries the burden. It discloses batch behavior, the return type (confirmation with ID(s)), and the semantic purpose of assumptions. Missing details like idempotency or error handling are minor for a create tool, so it earns a solid 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 well-structured with an intro, explanatory paragraph, and clear args/returns sections. It is slightly verbose by repeating schema details and including the non-schema 'ctx' argument, but every sentence contributes to usability.
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 (single vs batch), the description fully explains both modes, parameter requirements, and return value. An output schema exists, so return details are not needed. The description leaves no critical gaps for an add 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 100%, but the description adds value by explaining single vs batch parameter usage and clarifying that individual params are ignored when 'items' is provided. It also lists the required fields for single item mode. The mention of 'ctx' (not in schema) is a minor inconsistency, but overall it enhances parameter 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?
The description opens with 'Add a new assumption to the threat model,' which is a specific verb+resource statement. It clearly differentiates from sibling add_* tools (add_component, add_connection, etc.) by explicitly naming 'assumption' and the threat model context.
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 when-to-use guidance: single item mode vs batch mode, with explicit parameter requirements for each. While it doesn't name alternatives like update_assumption, the create operation is self-evident and the batch vs single distinction serves as 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?
Despite no annotations, the description discloses key behavioral details: batch mode is available, items overrides individual parameters when provided, and returns a confirmation message. It does not mention idempotency or permission requirements, but the core side effects are covered.
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 Args and Returns sections. A slight redundancy exists between the first sentence and the second paragraph, but overall it is concise and front-loaded with the core purpose.
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 no annotations, the description adequately covers modes, parameters, and return value. It does not address edge cases like duplicate additions or error handling, but those are less critical for a simple add operation and output schema exists.
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?
Schema coverage is 100% and the description adds meaningful semantics: it explains the relationship between items and individual parameters (items take precedence), and clarifies the required fields for each mode. This goes beyond the schema 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 the action: 'Add a component to a trust zone' and immediately notes batch support. It distinguishes from siblings like remove_component_from_zone and add_trust_zone by specifying the resource and relationship.
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 modes for single ('provide zone_id and component_id directly') and batch ('provide a list of dicts in the items parameter'). It does not explicitly name alternatives or exclusion conditions, but the context is clear enough for a mutation 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?
With no annotations, the description carries the full burden. It discloses the 200-character schema limit as IMPORTANT, describes the return value as 'a confirmation message with the threat ID(s)', and notes batch behavior and the ctx parameter's role. This goes beyond the schema, though it doesn't discuss error handling 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: summary, important note, Args list, and Returns. There is minor redundancy between the first two sentences, but it remains efficient for a tool with 11 parameters. Each section serves a purpose.
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?
It covers all parameters, the 200-character limit, and return behavior, and distinguishes single vs batch operations. Missing details like valid values for category/severity/likelihood or exact dict structure in 'items' are minor gaps, but overall it is sufficient for a threat-adding tool.
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?
Schema description coverage is 0%, so the description is the only source of parameter meaning. The Args block lists all 11 parameters, indicates required fields for single-item mode, and explains the batch 'items' parameter. It fully compensates for the bare 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 'Add a new threat to the model' and clarifies it adds one or more threats, distinguishing it from sibling tools like list_threats, update_threat, and delete_threat. The verb and object are explicit, and batch capability is stated, 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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear instructions for single-item vs batch modes: 'For single item: provide...' and 'For batch: provide...'. It explains when each mode is appropriate but does not explicitly mention alternatives or exclusions, hence a 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so this description carries the burden of behavioral disclosure. It specifies the return format as 'A markdown-formatted list' and mentions the ctx parameter for logging and error handling. While it does not explicitly state that the tool is read-only, the verb 'list' inherently implies a non-destructive operation, and the description adds useful detail about the output format.
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 concise but has minor redundancy: the first sentence 'List all available data models.' is repeated in the second sentence 'This tool lists all available data models.' However, the second sentence adds value by specifying the relationship with get_data_model_types. The structure is front-loaded with the main purpose, and the args/returns sections are clearly separated, making it easy to scan.
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 no parameters and a simple listing function, the description is complete. It explains what the tool returns, mentions its relationship to a sibling tool, and includes the ctx parameter for logging. Since an output schema exists, the description need not detail the return structure further. All essential information is provided.
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?
Since the input schema has zero parameters, the baseline is 4. The description mentions a 'ctx' argument for MCP context, which is not present in the schema. While this could cause slight confusion, it is likely an auto-injected parameter and the description helps explain its purpose. The tool is simple enough that no further parameter documentation is needed.
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 with a specific verb and resource: 'List all available data models.' It also distinguishes itself from related tools by noting these models 'can be used with get_data_model_types,' which is a sibling tool. This makes the purpose unambiguous and differentiates it from list_data_stores and other list operations.
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 by linking the tool to get_data_model_types, implying it is a precursor for that tool. However, it does not explicitly mention when not to use it or recommend alternative tools for different scenarios. Since it gives a clear usage context without explicit exclusions, a score of 4 is appropriate.
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 the return value (confirmation message with trust boundary ID(s)) and the batch override semantics. It also states it adds one or more trust boundaries to the system architecture. It doesn't cover error cases, validation, or idempotency, but for an add tool this is reasonable coverage.
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 usage explanation, a compact Args list, and a Returns line. Each section adds necessary information without redundancy or filler. It is appropriately sized for a tool with 6 parameters and two modes.
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 moderate complexity of the tool (6 parameters, single/batch modes) and the absence of annotations, the description fully covers what the tool does, how to use it in both modes, parameter roles, and what the caller should expect as a return. The presence of an output schema also reduces the burden of describing return values, but the Returns line still provides useful confirmation.
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 100%, so the baseline is 3. The description adds value beyond the schema by framing parameters in operational terms: 'name' and 'type' are required for single-item mode, 'items' accepts a list of dicts, and individual parameters are ignored in batch mode. This clarifies how to choose between modes and how parameters interact, which is not immediately obvious from 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 opens with "Add a new trust boundary," which is a specific verb+resource combination that clearly distinguishes this from siblings like add_trust_zone, add_crossing_point, and update_trust_boundary. The first sentence immediately establishes the tool's primary purpose.
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 explains the two modes of use: single-item (provide name/type directly) and batch (via 'items'). It also clearly states that when 'items' is provided, individual parameters are ignored. While it doesn't name alternative tools like update_trust_boundary or list_trust_boundaries, the creation context is unambiguous and the batch/single guidance is highly actionable.
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. It discloses the markdown return format and the internal contents (objectives, steps, tools, outputs). It also mentions the ctx parameter for logging/error handling. It does not explicitly say it is read-only, but the name and description strongly imply a non-mutating guidance retrieval.
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 succinct, front-loaded with the core purpose, and organized with Args and Returns sections. Every sentence contributes useful information with no fluff 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 simple guidance-retrieval tool, the description covers what the tool does, what content is included, and what the return type is. The presence of an output schema reduces the need to describe return values further. No significant gaps are apparent.
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 has zero parameters, which gives a baseline of 4. The description mentions a ctx argument for logging and error handling, adding a small layer of context beyond the schema (though that arg isn't in the schema properties). No further param semantics are needed.
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: 'Get detailed guidance for Phase 1: Business Context Analysis.' It clearly identifies the tool's scope and distinguishes it from sibling phase guidance tools like get_phase_2_guidance.
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 when to use this tool ('for Phase 1... for conducting business context analysis'), but it does not explicitly mention alternatives or when-not-to-use cases. Siblings like get_business_context_analysis_plan could be confused, but the phase labeling provides enough 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, so the description carries the full burden. It explicitly states the return format (markdown guide) and the content of the guide, and the 'Get' verb implies a read-only operation. It does not explicitly mention side effects or error behavior, but for a simple guidance-retrieval tool, this is reasonably 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 the phase and topic, followed by a brief content summary and structured Args/Returns sections. Every sentence contributes useful information, with no redundant or filler content.
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 zero-parameter, low-complexity guidance tool, the description is complete: it identifies the phase, explains what the guide includes, and specifies the return format. The output schema and sibling tool names provide additional context, and the description does not need to elaborate further.
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 zero parameters in the schema, the baseline is 4. The description adds context for a `ctx` argument used for logging and error handling, which is useful even though the argument is not represented in the schema. No further parameter clarification is needed.
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 ('Get') and a specific resource ('detailed guidance for Phase 3: Threat Actor Analysis'), immediately distinguishing it from sibling phase-guidance tools. It further clarifies the guide's contents (objectives, steps, tools, expected outputs), leaving no ambiguity about the tool's purpose.
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 this tool: when detailed Phase 3 threat actor analysis guidance is needed. It does not explicitly discuss alternatives or when not to use it, but the phase-specific naming among siblings provides sufficient contextual selection signal.
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?
Even though annotations are absent, the description reveals the tool is informational: it provides step-by-step guidance, objectives, steps, tools, and expected outputs, and returns a markdown guide. It does not mention side effects, but for a guidance-only tool this is sufficient and adds value beyond basic 'get 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?
The description is concise and well-structured: a clear purpose sentence, a brief elaboration of content, and standard Args/Returns sections. Every sentence contributes meaning without fluff, fitting a small utility tool.
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 (no parameters, output schema present), the description fully covers what it does, what content it includes, and what it returns. It provides enough context for an agent to decide to invoke it and to interpret the result.
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 tool has zero parameters, so the baseline is 4. The description mentions 'ctx' in Args despite no schema properties, adding a note about a framework-provided context; however, there are no user-facing parameters to elaborate, so this is acceptable and does not detract.
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 retrieves detailed guidance for Phase 8: Residual Risk Analysis, using a specific verb (Get) and resource (Phase 8 guidance). It is neatly distinguished from sibling phase guidance tools by the explicit phase number.
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 when needing to conduct residual risk analysis or when Phase 8 guidance is required. It does not explicitly mention alternatives or when not to use, but the sibling list of phase-specific guidance tools makes the context 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 does well: it states the operation is read-only (listing), describes the return as 'a markdown-formatted list of mitigations', and discloses the optional filtering behavior. This is transparent for a list operation with 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?
The description is concise and well-structured: a clear main statement, followed by a Args/Returns breakdown. Every sentence contributes value, with no filler or redundancy. The purpose is 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 list tool with two optional parameters and no complex side effects, the description is complete. It covers purpose, filtering options, and return format. No output schema is shown, but the stated markdown return is sufficient for an agent to know what to expect.
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?
Schema description coverage is 0%, but the description adds meaning to both parameters: 'type' and 'status' are explained as optional filters for mitigations. It goes beyond the schema's bare type definitions by specifying their role in narrowing the list.
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 'List all mitigations in the model' with a specific verb ('list') and resource ('mitigations'), and mentions it can be optionally filtered by type or status. This distinguishes it from sibling tools like get_mitigation (single item) and update_mitigation.
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 the tool: to list all mitigations, optionally filtered by type or status. However, it does not explicitly mention alternatives or when not to use it, though the filtering hints at use cases. No exclusions are stated.
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/awslabs/threat-modeling-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server