IA-QA Security — 30 tools

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context beyond annotations by stating that no API key is needed and that it runs entirely locally. Nothing contradicts the annotations.

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

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

The description is two sentences with no filler. It front-loads the core purpose, then lists key outputs, and ends with a valuable local-execution note. Every sentence earns its place.

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

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

The input schema fully documents the single parameter, the output schema covers return structure, and annotations cover safety. The description adds the essential context about same-template demographic variants and local execution, making the tool complete to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by specifying that responses must come from the same prompt template and by enumerating variant dimensions (gender, origin, age, tone), which clarifies expected values for variantId more concretely than the schema examples alone.

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

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

The description states a specific verb ('Analyse') and a specific resource ('a set of LLM responses generated from the same prompt template but with different demographic variants'). The mention of bias scoring plus sentiment and Jaccard similarity clearly distinguishes this from broader siblings like analyze_responses or compare_responses.

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

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

The description gives a clear usage context: use this when you have multiple LLM responses from the same prompt template with demographic variants. It does not explicitly name alternatives or give exclusion criteria, but the intended scenario is well implied.

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

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

The description adds meaningful behavioral context beyond annotations: it fetches the URL, inspects Set-Cookie headers, and flags specific insecure patterns. It also reveals the scoring model (weakest cookie, not average) and that average_score is separate. This adds value beyond the readOnlyHint and destructiveHint annotations, though it does not discuss potential side effects like redirects or network latency.

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

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

The description is a compact, information-dense paragraph with a clear front-loaded purpose. It lists checked attributes and flag conditions without fluff, and every sentence adds value. The scoring explanation is valuable and not redundant.

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

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

Despite having an output schema, the description explains the return values (per-cookie grades, overall score, average_score) and the scoring semantics. It covers the tool's behavior sufficiently for an agent to select and invoke it correctly, including edge cases like SameSite=None without Secure. No significant gaps remain.

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

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

The schema already provides 100% coverage for the single 'url' parameter with a clear description and example. The tool description adds 'any URL' and clarifies what the URL is used for, but this is marginal. Given the high 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.

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

The description begins with a specific verb+resource: 'Audit the security attributes of cookies set by any URL.' It clearly distinguishes from siblings like security_headers_check and web_security_audit by focusing exclusively on cookie attributes and set-cookie behavior. The list of inspected attributes and flagged patterns further specifies the tool's exact scope.

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

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

The description provides clear context for when to use the tool: it audits cookies from any URL and lists specific security checks. However, it does not explicitly name alternatives or state when not to use this tool, even though siblings like security_headers_check and web_security_audit overlap somewhat. The context is clear but exclusions are absent.

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

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

The description adds meaningful behavioral context beyond the annotations: it states the tool simulates a browser, returns the main response status, all Access-Control-* headers, the tested origin, and the preflight OPTIONS response. This informs the agent about the tool's output and behavior, complementing the readOnlyHint and destructiveHint annotations.

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

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

The description is two sentences, front-loaded with the primary purpose, then lists return values and usage guidance. Every sentence adds value with no redundancy or fluff.

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

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

With an output schema present and full schema coverage, the description covers purpose, behavior, and typical usage. It's complete for a simple diagnostic tool, though it could optionally mention error handling or network failure behavior for full completeness.

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

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

The input schema already provides descriptions for all three parameters (url, method, origin), with 100% coverage. The description doesn't add any additional parameter-specific details, so it meets the baseline but doesn't exceed it.

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

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

The description clearly states the tool's function: checking CORS configuration like a browser would. It mentions the resource (URL) and specific action, but doesn't explicitly distinguish itself from the sibling 'cors_test' tool, only from security auditing in general.

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

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

The description gives a clear usage context ('Use this for direct CORS debugging') and hints at an exclusion ('not just security auditing'). However, it does not name specific alternative tools, so it lacks explicit when-not-to-use instructions relative to siblings.

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

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

The description adds substantial behavioral nuance beyond the annotations: it explains that preflight OPTIONS requests are sent, what specific misconfigurations are detected, and critically clarifies the meaning of 'unknown' and 4xx responses. This is exactly the kind of context that helps an agent interpret results correctly.

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

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

The description is dense but every sentence earns its place: purpose, method, output format, and critical interpretation caveats are all included without redundancy. It is front-loaded with the core purpose and structured logically.

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

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

Given the tool's moderate complexity, the description is complete: it covers what the tool does, how it works, what it returns, and how to interpret ambiguous or error-like results. The output schema exists, and the description complements it with risk-level and per-origin result context.

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

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

The input schema already covers both parameters with 100% coverage, so the baseline is 3. The description does not add significant parameter-level detail beyond what the schema provides, though it does reinforce that multiple origins are tested by default.

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

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

The description clearly states the tool's function: 'Test a URL for CORS misconfigurations' and enumerates specific detection categories. It is specific and actionable, but it does not explicitly differentiate itself from the sibling tool 'cors_checker', so it stops short of a 5.

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

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

The description provides clear context for when the tool is appropriate: testing URLs for CORS misconfiguration issues. It does not mention alternatives or exclusions, but the intended use case is unambiguous and well-scoped.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds crucial behavior beyond annotations: it explicitly states the signature is NOT verified, which is a key security-relevant trait. It also mentions expiry reporting. This adds meaningful context without redundancy.

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

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

The description is two sentences, front-loaded with the core function. Every sentence adds value: the first states what it does, the second gives usage guidance. No fluff or repetition.

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

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

The tool is simple with one parameter and an output schema, so the description does not need to explain return values. It covers the purpose, key behavior (no signature verification), and typical use cases, making it fully sufficient 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.

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

The schema covers 100% of the parameter, including a description of the JWT format. The description does not add extra parameter-specific details beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Decode') and resource ('JWT'), clearly stating it returns header and payload without verifying the signature. It distinguishes itself from siblings like base64_decode by focusing specifically on JWT structure and expiry reporting. 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.

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

The description provides a clear use case: 'Use to inspect claims (sub, iss, exp, roles) during debugging or when integrating with an auth provider.' This gives context for when to use the tool, though it does not explicitly mention exclusions or alternatives, which prevents a top score.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds contextual behavior: it returns findings with severity and highlights what types of secrets are detected. This goes beyond the annotations, revealing the tool's output characteristics without contradicting the declared safety profile.

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

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

The description is three sentences: the first defines the core action and scope, the second states the return value, and the third gives usage guidance. It is front-loaded, informative, and contains no filler words.

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

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

Given the presence of a complete input schema (100% coverage) and an output schema, the description covers the tool's purpose, target content, return behavior, and usage context. It is fully adequate for an agent to select and invoke this tool correctly.

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

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

Schema coverage is 100%, so the parameters 'input' and 'filename' are fully described in the schema. The description does not provide additional parameter-level details beyond implying that 'input' contains code/config content. Baseline 3 is appropriate.

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

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

The description explicitly states the tool scans code/config files for hardcoded secrets and provides a comprehensive list of secret types (AWS keys, GitHub tokens, API keys, etc.). It uses a specific verb 'scan' and resource, making the purpose unambiguous and distinguishable from generic scanning tools.

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

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

The description gives a clear usage directive: 'Run before every commit.' This provides strong contextual guidance, though it does not explicitly mention alternatives or when not to use the tool. The lack of exclusions makes it a 4 rather than a 5.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds behavioral context such as ranking by IDF-weighted relevance and that common words do not inflate results. It also notes the optional inclusion of inputSchemas in results, which is a useful behavioral detail beyond the annotations.

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

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

The description is three sentences, each earning its place: the first states the core action and timing, the second describes the return content, and the third provides the category list. There is no redundancy or filler.

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

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

Given the presence of an output schema, full parameter documentation, and annotations, the description supplies the missing contextual information: when to invoke it and how results are ranked. It covers the tool's role in the larger catalogue and does so without needing to explain return structures.

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

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

Schema description coverage is 100%, so each parameter (query, category, max_results, with_schema) is already well-documented in the input schema. The description adds no additional parameter-specific meaning beyond what the schema provides. It does list the allowed categories, but this is also present in the schema description for the category parameter.

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

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

The description uses a specific verb 'Search' with a clear resource ('available MCP tools') and includes the scope ('by keyword or category before calling them'). It also distinguishes itself from siblings by emphasizing it is a catalogue exploration tool, not a functional tool. The return value (tool names, descriptions, optionally schemas) is stated directly.

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

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

The description explicitly states when to use the tool: 'Call this when you are unsure which tool to use or want to explore the catalogue.' This provides clear context for use. It does not explicitly mention when not to use it or list alternative tools, but given the meta-purpose, this is sufficient.

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

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

Annotations already establish safety (read-only, idempotent, non-destructive). The description adds the behavioral logic of the validation checks, which is beyond the annotations. It does not discuss error handling, but the presence of an output schema offsets that need.

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

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

Two sentences, front-loaded with the core function, followed by context. No redundant information.

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

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

The tool is well-described for its complexity. The output schema and annotations cover return values and safety. The description covers validations performed and target platforms. Minor ambiguity about what 'expected schema' means relative to the required/optional args format, but it's adequately complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's reference to 'arguments match expected schema' adds little beyond the schema's own descriptions. It does not clarify the allowed_functions structure beyond what's in the schema.

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

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

The description uses a specific verb 'Validate' with a clear resource 'LLM function call / tool_use output', and enumerates the exact validation checks (name in allowed list, arguments schema, extra/missing args). This clearly distinguishes it from generic validators like llm_output_validator or json_schema_validate.

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

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

It states the use case: 'For OpenAI function calling & MCP tool_use testing.' This provides clear context for when to use the tool. It does not explicitly name alternatives or when not to use it, but the targeted scope is clear enough.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds algorithm support and default behavior, but it does not disclose output formatting details (e.g., lowercase hex) or any security nuances such as avoiding MD5 in production. With annotations provided, this level of added context is adequate but not exceptional.

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

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

The description is two sentences long, front-loads the core function, and provides practical context in the second sentence. Every word earns its place with no redundancy or filler.

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

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

For a simple, pure, read-only cryptographic utility with a full input schema, output schema, and strong annotations, the description is complete. It covers purpose, supported algorithms, defaults, and real-world use cases, leaving no meaningful gap 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.

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

Schema description coverage is 100%, so the schema already fully describes message, secret, encoding, and algorithm. The description repeats the algorithm choices and default but adds no new parameter-level meaning beyond what the schema provides, placing it at the baseline of 3.

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

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

The description starts with a specific action, 'Compute an HMAC signature for a message using a secret key,' clearly identifying the tool's resource and operation. It distinguishes itself from sibling tools like hash_text and base64_encode by explicitly naming HMAC and keyed signing, and it reinforces this with concrete use cases such as API signing and webhook verification.

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

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

The description lists explicit usage contexts: 'API request signing, webhook verification (GitHub, Stripe, Twilio), and JWT validation.' While it does not mention when not to use the tool or name alternatives, the stated use cases are clear enough for an agent to select this tool among siblings.

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

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

Annotations already mark the tool as read-only and non-destructive. The description adds the cryptographically secure, random nature of the output and the length range, which is useful behavioral context beyond what annotations declare. It does not contradict annotations.

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

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

The description is concise, front-loaded with the verb, and every sentence adds value: purpose, feature summary, and use cases. No fluff.

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

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

With four optional parameters fully described in the schema and an output schema present (as indicated by context), the description provides sufficient context for selection and invocation. It includes purpose, capabilities, and appropriate use cases, making it complete for a generator tool.

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

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

Schema coverage is 100%, so the description does not need to repeat parameter details. The description mentions the configurable features (length, uppercase, digits, symbols) but adds no deeper semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb ('Generate'), a specific resource ('password'), and implementation detail ('using crypto.randomBytes'). It distinguishes from sibling tools like generate_uuid or generate_hmac by focusing on passwords.

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

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

The description provides explicit use cases ('resetting user passwords, seeding test accounts, or generating API secrets'), but does not mention when NOT to use it or alternatives. Sibling tools are not directly referenced, but the guidance is clear enough for most agents.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by enumerating supported rule types and stating that it returns pass/fail per rule, which is useful beyond the annotations.

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

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

The description is a single sentence that front-loads the core purpose, lists rule examples for clarity, and ends with the return behavior. Every word earns its place; there is no redundancy or fluff.

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

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

Given the tool's modest complexity (two parameters) and the presence of an output schema, the description is adequately complete. It mentions the return format (pass/fail per rule) and enumerates rule types, though it does not address edge cases like invalid regex, which could be inferred from the schema.

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

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

The input schema already provides descriptions for both parameters, with 100% coverage. The description's list of rule types echoes the enum values in the schema without adding new semantic detail, so it contributes little beyond the structured documentation.

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

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

The description clearly states what the tool does: tests an LLM response against guardrail rules, with a specific verb and resource. It lists the rule types, which distinguishes it from sibling tools like toxicity_scan or prompt_injection_scan that focus on specific safety dimensions.

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

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

The description establishes a clear context for use: validating LLM responses against custom guardrail rules. It does not explicitly name alternatives or exclusion criteria, but the specific rule categories imply a general-purpose guardrail testing role distinct from more specialized sibling tools.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds behavioral traits such as 'cryptographic' and 'fixed-length digest,' and explains algorithm support including the default (SHA-256) and a recommendation for password hashing. This enriches the agent's understanding of output characteristics without contradicting annotations.

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

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

The description is two crisp sentences: the first states the core function, the second packs use cases and algorithm list. No filler words.

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

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

For a simple tool with two parameters and an output schema, the description covers purpose, usage contexts, algorithm choices, and output nature (fixed-length digest). Combined with annotations and schema, the agent has everything needed to select and invoke it correctly.

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

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

The schema describes both parameters with 100% coverage, so the description doesn't need to repeat them. It does provide a small addition by recommending 'prefer SHA-256+' for password hashing, which helps with algorithm selection, but otherwise adds little beyond the schema.

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

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

The description uses the specific verb 'Compute' and resource 'cryptographic hash of a text string,' clearly distinguishing it from siblings like base64_encode (encoding) and generate_hmac (keyed hash). It also lists concrete use cases (data integrity, content fingerprints, password hashing), 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.

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

The description explicitly states when to use the tool: 'Use when you need to verify data integrity, generate content fingerprints, hash passwords (prefer SHA-256+), or produce a fixed-length digest of any input.' This provides clear usage context, though it does not explicitly mention alternative tools like generate_hmac for keyed hashes, so it lacks explicit exclusions.

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

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

Annotations already declare readOnly and idempotent, which the description reinforces with a clear non-destructive lookup nature. The description adds value by specifying the registry scope and reporting behavior for non-registered codes (registered: false), and clarifies the meaning of cacheability per RFC 9110. However, it doesn't mention response format details like pagination or error codes, but given the annotations and output schema, the marginal gap is acceptable.

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

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

The description is compact, two sentences, and conveys all necessary details: purpose, scope, edge cases, and specific terminology. Zero fluff, front-loaded with the primary function.

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

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

The tool is simple (one parameter, output schema present, no nested objects). The description covers the registry scope, non-registry behavior, and the meaning of cacheability. It might benefit from mentioning the output format or the returning of RFC references, but the output schema presumably covers that. Not enough to score 5, but solidly complete for the tool's complexity.

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

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

Schema coverage is 100% (code parameter fully described). The description does not add extra syntax or formatting details beyond what the schema provides, but the schema itself is sufficient given the single, self-explanatory parameter. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Look up') with a clear resource ('HTTP status code') and specifies the exact scope (IANA registry, 1xx-5xx including edge codes). It clearly distinguishes from sibling tools which are mostly unrelated (encoding, formatting, analysis of other domains).

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

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

The description clearly states the tool is for looking up detailed info about HTTP status codes, covering the entire IANA registry. It does not explicitly mention alternative tools or when not to use it, but the broad coverage and domain specificity effectively imply usage context, and it explicitly notes the behavior for non-registry codes.

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

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

Annotations already mark the tool as read-only and non-destructive. The description adds that it runs N iterations and returns latency statistics, which is beyond the hints. It also mentions support for GET/POST, but does not contradict the read-only annotation since the tool only measures timing.

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

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

The description is three concise sentences: purpose, behavior/return values, and use case. It is front-loaded and contains no filler.

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

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

The tool has a rich schema and output schema, and the description covers the main behavior and intended use. No additional details are needed 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.

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

Schema coverage is 100%, with complete descriptions for 'endpoints' and 'iterations'. The description's mention of 'N iterations' and 'GET/POST' mirrors the schema without adding new semantic details, hence the baseline score.

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

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

The description uses the specific verb 'measure' and identifies the resource as 'response time of one or more HTTP endpoints (GET/POST)'. It clearly distinguishes from siblings like mcp_server_health_check by focusing on latency and benchmark scenarios.

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

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

The description explicitly states it is 'Useful for API and MCP server benchmarking', giving clear context for when to deploy it. It does not mention alternatives or exclusion criteria, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so no contradiction. The description adds 'Returns actionable warnings' and the list of lint checks, but it does not disclose edge cases, behavior on invalid input, or the exact structure of warnings, which the output schema may not fully convey.

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

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

The description is one dense, front-loaded sentence that efficiently lists the tool's scope and output. Every phrase earns its place—no filler or repetition of schema content.

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

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

Given the low complexity (one parameter), rich annotations, and presence of an output schema, the description is largely complete. It covers purpose, checks, and return value. It slightly lacks explicit context about preconditions or alternative tool disambiguation, but these are minor given the tool's simplicity.

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

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

Schema description coverage is 100% for the single tool_definition parameter, so baseline is 3. The description repeats the parameter's purpose (linting that definition) but adds no extra semantic detail beyond the schema's 'object with name, description, inputSchema'.

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

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

The description uses a specific verb ('Lint') and resource ('MCP tool definition') and enumerates concrete aspects (naming conventions, description quality, schema completeness, required fields consistency, description length). This clearly distinguishes it from sibling tools like mcp_server_evaluate or validate_mcp_response.

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

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

The description implies usage: when you need to validate an MCP tool definition against best practices. However, it does not explicitly state when to prefer this over alternatives, nor does it mention exclusions or prerequisites, leaving some ambiguity.

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

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

Annotations only declare it a safe, open-world read; the description adds substantial context beyond that: no credentials are sent so auth-required servers yield INCONCLUSIVE with a null score, a 301/302 on POST caps the verdict at FIX, private/local addresses are refused, and structuredContent is only checked for presence rather than validated against outputSchema. These are exactly the operational behaviors an agent could not infer from annotations.

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

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

Purpose is front-loaded in the first clause, and the check inventory that follows is dense but each item carries information. It reads as a long comma-chained sentence rather than structured lines, which slightly hurts scanability, but there is little true filler.

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

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

For a tool with an output schema, the description still summarizes the return contract (PASS/FIX/BLOCK, 0-100 score, per-check details, INCONCLUSIVE with null score) and covers preconditions, network constraints, and score-affecting edge cases. Nothing an agent needs to invoke it correctly appears missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema for test_tool_name: if omitted, the first readOnlyHint:true tool is called, and otherwise the call is skipped and not scored. That clarifies the consequence of leaving the parameter out, which the schema alone does not.

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

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

States a specific verb and resource — 'Run a compliance evaluation against a live MCP server over Streamable HTTP' — and immediately enumerates the checks it performs (initialize, tools/list, ping, unknown method, tools/call, GET, latency). It is clearly separable from siblings like mcp_schema_lint and mcp_server_health_check, the latter of which it explicitly delegates stdio cases to.

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

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

Gives explicit routing rules: stdio servers and private/local addresses cannot be reached here, and their tools/list output should be pasted into mcp_server_health_check instead. It also states when a tools/call is skipped versus executed (test_tool_name or a readOnlyHint:true tool), which is the key selection decision for this tool.

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

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

Beyond the read-only/idempotent annotations, the description discloses the actual validation rules (name charset and length, camelCase and zero-parameter tools accepted, inputSchema must be object, required fields listed in properties), the strict documentation checks, the PASS/WARN/FAIL derivation, and the important caveat that a tools/list carries no server name so those checks are not scored. That is substantial behavioral disclosure an agent could not get from annotations.

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

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

Front-loaded with the core purpose and the accepted input forms, then the rules, then the verdict semantics. Dense but nearly every clause carries information; the parenthetical spec rules are long, though they earn their place as they define the contract.

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

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

An output schema exists, so return-value structure need not be re-explained; the description still supplies verdict meanings and the correct gating expression, plus the tools/list scoring caveat. That is complete for a two-parameter offline validator.

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

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

Schema coverage is 100% and the schema already enumerates the accepted manifest forms and the strict semantics (≥20 chars, parameter description and type), so the description largely restates the structured fields. The only marginal addition is emphasis that `strict` extends validation to documentation, which is already stated in the property description.

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

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

States a specific verb and resource ('Check an MCP server's tool definitions') plus a key scope qualifier ('without contacting it'), which distinguishes it from live-server tools. It does not explicitly separate itself from the closest sibling, mcp_schema_lint, leaving some ambiguity for an agent choosing between the two.

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

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

Gives concrete when-to-use conditions: a server not deployed yet, a stdio server, or a CI gate, and names the gating mechanism ('Gate on verdict or on checks[tool_quality].pass'). It stops short of naming alternatives or exclusions, so an agent must infer when the sibling lint tool is preferred.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description supplements this with valuable behavioral details: 'Detects multi-value headers, masks Authorization values, and optionally audits for missing security headers.' This adds context about data handling without contradicting the annotation.

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

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

Two sentences, front-loaded with the main verb action, and every clause adds substantive information. No wasted words or redundancy with schema.

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

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

Given the tool's low complexity, comprehensive annotations, and presence of an output schema, the description covers purpose, key behaviors, and optional features. It does not need to describe return values because the output schema exists. The description is fully adequate for an agent to select and use the tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description enriches the 'headers' parameter by explaining multi-value detection and Authorization masking, and adds security header examples (HSTS, CSP, X-Frame-Options) that clarify the 'analyze_security' parameter. This goes beyond the schema's static descriptions.

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

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

The description clearly states 'Parse a raw HTTP headers block into a structured JSON object,' which is a specific verb+resource+output. It distinguishes itself from siblings like parse_csv and security_headers_check by mentioning multi-value detection, Authorization masking, and optional security auditing.

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

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

The description implies the use case: when you have a raw HTTP headers block and want structured JSON. It clearly notes the optional security audit feature, which hints at when to use this vs a dedicated security checker, but does not explicitly name alternatives or exclude cases.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses nuanced behavior: how quoted/fenced content is handled (severity reduction, never suppressed) and that live imperatives keep full severity, providing extra transparency.

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

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

The description is detailed and informative but somewhat lengthy with examples. It is well-structured as a single paragraph explaining purpose and behavior, though it could be slightly more concise.

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

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

No output schema is provided, but the description implies the output includes severity levels and detection results. It covers the essential context for using the tool, though it stops short of explicit return format details.

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

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

The input schema already provides descriptions for both parameters ('input' and 'sensitivity'). The description does not add further parameter-level detail, but since schema coverage is 100%, baseline 3 is appropriate.

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

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

The description clearly states the tool's function: scanning user input for prompt injection patterns, and lists specific categories (system prompt overrides, jailbreak attempts, etc.). It is unambiguous and distinguishes the tool from typical text processing tools.

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

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

The description indicates the tool is for security scanning of user-provided text, but does not explicitly state when not to use it or mention alternatives. However, the intent is clear enough for typical use cases.

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

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

Adds context beyond annotations: ratings are aggregated on a public dashboard, comment truncation behavior is described, and the tool's write action is clear (no annotation contradiction).

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

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

Single efficient paragraph that front-loads purpose, then moves through scoring guidelines, dashboard note, usage rule, and example—every sentence earns its place.

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

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

For a simple 3-param tool with output schema, the description covers what the tool does, when to use it, how to use parameters, behavioral quirks (truncation), and an example—no gaps.

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

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

Schema coverage is 100%; the description enriches each parameter with usage guidance (e.g., comment is 'the most valuable part', score scale explained, tool_name example) and provides a full invocation example.

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

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

The description uses a specific verb ("Give") and resource ("usage feedback on an IA-QA MCP tool"), and clearly distinguishes this rating tool from the many sibling utilities by its unique role of collecting feedback.

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

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

Explicit criteria for when to rate low (1-2) vs high (4-5), and a direct instruction to skip routine successes ('we want signal, not praise'), plus a concrete example showing how to call the tool.

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

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

Annotations already mark it as read-only and idempotent, and the description adds behavioral detail: it replaces specific PII types with formatted [REDACTED_TYPE] placeholders. It also communicates safety for downstream operations, which supplements the annotations without contradiction.

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

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

Three sentences, each earning its place: action, replacement behavior, and recommended use case. No filler or redundant restatement.

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

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

For a single-input utility with a straightforward output, the description plus annotations and output schema fully cover operation. It explains what the tool does, what it redacts, and when to use it.

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

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

Schema coverage is 100%, with descriptions for input, types, and marker. The tool description merely lists the same entity types found in the schema and doesn't add new parameter-level semantics, so it meets the baseline.

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

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

The description uses a clear verb ('detect and redact') with a specific resource (PII from text) and enumerates the exact entity types covered. This distinguishes it from sibling text-analysis tools like detect_secrets or bias_detect, making the purpose immediately obvious.

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

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

It explicitly recommends use before logging or sending to an LLM, giving a concrete scenario for when to use the tool. It doesn't name alternatives or exclusions, but the context is clear enough for an agent to choose this over other text utilities.

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

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

Discloses that it is 100% regex-based with zero network calls, which is not covered by annotations. Annotations already declare readOnlyHint=true and destructiveHint=false, but description adds that it's regex-based (not ML) and doesn't exfiltrate data—critical for trust. No contradiction.

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

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

Two sentences, no fluff, front-loaded with purpose. Every word contributes: listing secret types, return info, usage timing, and behavioral caveat. Perfectly sized for quick understanding.

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

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

Given simple input (string) and optional types, plus output schema exists, the description fully covers what's needed: return format, usage timing, and safety behavior. No gaps for an agent to misuse the tool.

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

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

Schema coverage is 100% with descriptions, but description adds detail on the 'types' parameter: lists default 'all' and gives examples (e.g., 'aws_access_key'), and notes that unknown values are rejected. This goes beyond schema by clarifying behavior on invalid input.

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

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

Clearly states it scans text/code for leaked secrets, lists specific types (API keys, private keys, JWTs, etc.) and return findings. Distinguishes from sibling 'detect_secrets' by specifying the comprehensive families and usage context, making it the go-to secret scanner.

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

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

Explicitly instructs when to use: before committing code, sharing logs, or sending text to an LLM. This clearly delineates use cases and suggests this is the recommended tool for secret scanning, differentiating from siblings like 'detect_secrets' and 'redact_pii'.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context: the A–F grading scale, the overall 0–100 score, missing header reporting, fix snippets, and the critical limitation that the server cannot reach localhost/private IPs. This goes well beyond what annotations alone convey.

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

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

Two dense, well-organized sentences cover the tool's purpose, input modes, grading criteria, output details, and a usage caveat. Every sentence carries substantive information with no redundancy or fluff.

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

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

With an output schema present, the description is not obligated to detail return values, but it still summarizes the overall score, per-header grades, missing headers, and fix snippets. The input modes and limitations are thoroughly explained, making the tool usable without needing to inspect the schema.

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

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

The schema covers both parameters 100%, so the baseline is 3. The description adds meaning by framing the tool as accepting 'a public URL OR raw response headers', clarifying that one of the two is expected and providing a practical decision rule for which to use. This is useful guidance beyond the individual parameter descriptions.

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

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

The description uses a specific verb ('Analyse') and resource ('HTTP security headers') and clearly distinguishes two input modes (public URL or raw headers). It lists the exact headers graded and the output components, making it unmistakable what the tool does and how it differs from sibling tools like cookie_security_audit or cors_checker.

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

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

The description gives explicit guidance on when to use the `headers` parameter instead of `url` (for localhost/private targets the server cannot reach), which is directly actionable. It doesn't explicitly name sibling tools as alternatives, but the domain and parameter guidance provide clear context for when this tool is appropriate.

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

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

The description reveals extensive behavioral details: it orchestrates 7 deterministic checks, includes an optional LLM deep analysis, explains how PII gates the verdict (SSN/credit card forces BLOCK, email forces FIX), and notes edge cases like regex matching pitfalls. This goes well beyond the annotations and provides high transparency.

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

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

The description is relatively long but information-dense, covering a complex tool with multiple checks, scoring, and edge cases. It is well-structured with a clear main purpose up front and detailed specifics afterward, avoiding unnecessary fluff.

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

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

The description gives a good overview of the output (verdict, score, per-check results, recommendations) and covers key behaviors and edge cases. While the output schema is not explicitly shown, the description provides enough context for the caller to understand what to expect. It does not detail every possible scenario but is reasonably complete for the complexity.

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

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

The input schema already provides detailed descriptions for each parameter (e.g., model, prompt, source). The tool description does not add significant new meaning beyond what is already in the schema; it focuses on tool behavior rather than parameter semantics. Since schema coverage is 100%, the baseline is 3.

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

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

The description clearly states the tool's primary function as a comprehensive AI guardrail analysis on LLM responses, listing the specific checks it orchestrates. It distinguishes itself from individual sibling tools like toxicity_scan or prompt_injection_scan by positioning itself as a unified safety gate.

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

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

The description explicitly recommends using this as a single-call safety gate before surfacing LLM output, giving a clear usage scenario. However, it does not explicitly contrast it with the individual sibling tools or state when not to use it, so it falls short of perfect explicitness.

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

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

Annotations already mark readOnlyHint=true and destructiveHint=false, and the description further explains that it detects expired, self-signed, and weak certificates, and returns a grade. This adds useful behavioral context beyond the annotations, such as its network-based external host checking. No contradiction.

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

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

Two concise sentences that front-load the core function, then list key outputs and use cases. Every sentence adds value, and there's no redundancy with the schema or annotations.

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

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

With an output schema present and clear annotations, the description need not restate return structures. It provides the essential behavioral and usage context, including what the tool checks, what it returns, and when to use it. This is complete 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.

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

Schema description coverage is 100%, with both host and port having clear descriptions. The description reinforces the host parameter by saying 'any HTTPS host' and implies the default port behavior indirectly, but adds no extra parameter details beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the action (analyse SSL/TLS certificate) and resource (any HTTPS host), and enumerates specific return values (subject, issuer, validity, grade). This distinguishes it from sibling security tools like security_headers_check or web_security_audit, which target other aspects of web security.

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

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

Provides explicit use cases: 'audit TLS posture before production deployment or during security reviews.' It doesn't explicitly contrast with sibling tools, but the focused scope makes the intended usage clear. It would be stronger with an explicit 'for checking HTTP headers use security_headers_check,' but the context is sufficient.

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

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

The description discloses the underlying methodology (lexical + structural pattern matching, not semantic classifier) and explains the output (per-category risk plus named rules). This goes beyond the basic annotations, providing substantial transparency about limitations and behavior.

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

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

The description is two sentences, tightly packed with purpose, method, output, and usage context. No unnecessary words or repetition, making it highly efficient.

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

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

The description covers what the tool does, how it works, what it returns, and when to use it. It even clarifies limitations (not a calibrated CI gate) and provides an example of output ('named rules that fired'). This is comprehensive for the tool's complexity.

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

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

The schema already provides descriptions for both parameters (text and categories) with the default for categories. The description adds little beyond listing the categories, which is already in the schema. Since schema coverage is 100%, the baseline is 3, and the description does not significantly enhance parameter understanding.

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

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

The description clearly states the tool's function: scanning text for toxic language, hate speech, and other categories. It also distinctively identifies the tool as a toxicity scanner among many siblings, with no ambiguity.

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

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

The description provides explicit usage context ('LLM safety guardrail testing and triage') and cautions that it is not a calibrated CI gate. While it doesn't name alternatives, it gives clear guidance on appropriate use cases.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds real behavior beyond them: deterministic/no-LLM, the precise error-detection heuristic (is_error fields, error markers, leading-token markers), and the guarantee that model prose is never keyword-scanned. It omits auth/rate-limit context but materially enriches the behavioral picture.

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

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

Front-loads the mechanism and the assertion catalogue before the usage recommendation, and is dense with content. It is long and the 'Returns...' clause partially duplicates the output schema, which keeps it off a 5.

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

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

With an output schema present, return values needn't be re-explained, and the description still adds the empty-trace warning and error_signal behavior. Format auto-detection and assertion semantics are covered, leaving it complete for a 3-param tool, though the CI/CD integration angle is asserted rather than explained.

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

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

Schema description coverage is 100%, so the schema already documents format, assertions, and every nested field. The description restates assertion types and semantics (e.g., recovery) but adds little syntax detail beyond what the schema/enum already provide, so baseline 3 applies.

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

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

States a specific verb+resource ('Run declarative assertions on an agent trace') and immediately scopes the input formats it accepts. It is unmistakably distinct from siblings like function_call_validate, guardrail_test, or run_semantic_tests because it names its exact mechanism (deterministic assertions, no LLM call).

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

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

Ends with an explicit use case — 'gate CI/CD on agent behavior correctness' — and the 'No LLM call — deterministic' line signals when to prefer this over LLM-based evaluators. It does not name a specific alternative or a when-not condition, so it falls short of the top anchor.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read-only operation. The description adds that it performs checks on a provided response, which is useful but does not elaborate on error handling or output behavior beyond what annotations imply.

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

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

The description is two sentences long, front-loaded with the core purpose, and every word earns its place. No filler or redundant detail.

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

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

Given the output schema exists and parameter coverage is 100%, the description sufficiently covers the tool's purpose and usage. It could briefly mention that the tool does not call the MCP server itself, but this is not essential for selection or invocation.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters. The description only generically references 'checks to perform,' adding no meaningful detail beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool validates MCP tool responses against format, schema, and content rules. It names the specific resource (MCP tool response) and the action (validate), but does not explicitly distinguish it from sibling validation tools like json_schema_validate or mcp_schema_lint.

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

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

It provides clear usage context: 'Use this to QA-test any MCP server tool.' This tells the agent when to use the tool, but it does not mention exclusions or explicitly compare to alternatives, falling short of a 5.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds the return component breakdown but does not discuss edge cases like invalid URLs or normalization behavior, which would add extra value beyond annotations.

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

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

Two short, front-loaded sentences cover purpose, validation aspect, and return contents. Every word earns its place with no redundancy or fluff.

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

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

Given the simple one-parameter signature, existing output schema, and full annotations, the description is sufficient for an agent to select and invoke the tool correctly. It even mentions the return structure, making the tool's behavior immediately clear.

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

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

Schema description coverage is 100% (the parameter is already described as 'URL to validate and parse'). The description essentially restates the input purpose and does not add format or behavior details beyond what the schema provides.

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

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

The description uses a specific verb phrase 'Parse and validate a URL' and clearly identifies the resource and output (decomposed components). This distinguishes it from sibling tools like url_encode/url_decode or validate_email.

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

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

It clearly implies use for parsing/validating URLs and describes what will be returned, giving clear context. However, it does not explicitly mention when not to use it or point to an alternative sibling tool.

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

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

Discloses that it runs the four checks in parallel, merges findings, invokes an LLM to rank vulnerabilities, generate a remediation roadmap, and produce fix snippets, and returns both raw audit data and AI analysis. Annotations already cover read-only/non-destructive behavior, and the description adds valuable orchestration and LLM behavior without contradicting annotations.

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

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

Four sentences with a front-loaded main purpose and a structured enumerated list of the AI analysis outputs. The length is justified for an orchestrator of this complexity, though it could be slightly tightened without losing value.

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

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

For a high-complexity orchestrator, it covers the sub-checks performed, the parallel execution model, the AI analysis outputs, and the combined return payload; the output schema handles return-value details. It does not mention failure behavior, timing, or cost, but it is sufficiently complete for tool selection and invocation.

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

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

Schema coverage is 100%, and the schema already documents url, model, and api_key with defaults and the 'none' option for skipping AI analysis. The description reinforces the purpose of the model/api_key parameters but does not add semantics beyond what the schema provides, so the baseline 3 is appropriate.

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

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

Clearly states it runs a comprehensive web security audit combining headers, SSL, CORS, and cookies checks, then produces an LLM-generated remediation plan. It explicitly names the exact sub-tools it orchestrates (security_headers_check, ssl_certificate_check, cors_test, cookie_security_audit), distinguishing it from those siblings.

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

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

Provides clear context with 'Use this as a one-click security posture assessment,' which signals when the bundled orchestration is appropriate versus running individual checks. It does not explicitly state when not to use it or name alternatives, so it stops short of a 5.

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