AgentAegis

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, but the description adds valuable behavioral context: it costs $1 per call and does not connect to an identity provider. These are non-obvious traits that help agents anticipate side effects and dependencies. No contradiction with 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 long and highly efficient. It front-loads the primary purpose, then states the data-source limitation and cost. Every sentence adds necessary information without redundancy.

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

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

The description covers the core purpose, data source, and cost, which is useful, but it lacks details on the return format or output structure despite there being no output schema. It also leaves two parameters underspecified. Given the tool's moderate complexity, additional context about findings or result shape would improve completeness.

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

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

Schema description coverage is low at 25% (only previous_scan_id is described). The description only vaguely references 'user and role assignments,' which maps to the required 'users' parameter, but it omits any explanation of 'admin_roles' and 'sensitive_permissions.' This leaves key parameter semantics unclear, and the description does little to compensate.

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: 'Review user and role assignments you supply against least-privilege, flagging excessive, stale or orphaned access.' It uses a specific verb, resource, and outcome, and distinguishes itself from sibling audit tools by noting it 'does not connect to an identity provider,' clarifying its offline analysis 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 analyzes caller-supplied data and does not connect to an identity provider. This implies it is suitable for offline analysis of provided assignments, but it stops short of explicitly naming alternatives or stating 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.

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

Annotations already indicate read-only and idempotent behavior. The description adds valuable context beyond annotations by stating the call is free and by detailing the exact data returned (balance, limit, usage, tool affordability). No contradictions found.

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

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

A single, well-structured sentence that front-loads the action and lists specific return items without any fluff or repetition. Every word adds 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 zero-parameter, no-output-schema tool, the description fully explains what the agent can expect: balance, monthly limit, current usage, and a breakdown of affordable tools. It is sufficient for an agent to decide to call and interpret the result.

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

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

The tool takes zero parameters, so the schema covers everything (100% coverage). The description correctly describes what the tool returns, which is the relevant semantic information for a parameterless call.

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 ('Returns') and names exactly what is returned: prepaid balance, monthly limit, current usage, and a tool affordability breakdown. This clearly distinguishes the tool from the sibling security scan and audit 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 implicitly suggests use when checking account balance or affordability, and the 'Free to call' note hints at no cost penalty. However, it does not explicitly state when to use this tool vs. alternatives, or any 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 readOnlyHint and idempotentHint, so the safety profile is known. The description adds value by enumerating the fields returned and noting it is 'Free to call,' which is helpful context beyond the schema. It does not contradict 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, front-loaded with the action and purpose, and every word earns its place. 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 no required parameters and no output schema, but the description explicitly lists the fields returned and mentions the optional filters. This is complete enough for an agent to understand what the tool does and what it returns.

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 each parameter already described in detail. The description only repeats the parameter names ('limit/tool/target/since') without adding new semantic meaning, so it meets the baseline for schema-covered parameters.

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

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

The description clearly states the tool lists recent scans with specific fields (scan_id, tool, target, status, time), which is a specific verb+resource. It distinguishes from sibling tools like agent_scan_get by focusing on browsing history rather than retrieving a single scan.

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 clear context ('so you can retrieve or chain from a prior result') and mentions optional filters, which helps an agent know when to call it. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the baseline safety profile is clear. The description adds behavioral context beyond annotations: it mentions the stored full output is included, it's scoped to 'your prior scans' (ownership), and it's free to call (cost behavior). This is useful context not present in the annotations.

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

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

The description is a single sentence that leads with the action, then provides the output detail, the use case, and the cost note. Every phrase earns its place; there is no fluff or redundancy. It is appropriately compact for a simple retrieval tool.

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 low-complexity retrieval tool with two well-described parameters and no output schema, the description covers the essential purpose, usage context, and cost. It doesn't describe error handling or response shape in detail, but the 'including the stored full output' gives a high-level view of the return. Given the simplicity and strong annotations, this is sufficiently 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 schema already documents both parameters clearly. The description adds marginal value by echoing the key parameter concepts ('by scan_id', 'including the stored full output'), but it doesn't introduce new semantics or clarify any ambiguity beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Retrieves') plus a clear resource ('one of your prior scans') and identifier ('by scan_id'). It also distinguishes itself from scanning tools by focusing on retrieving past results, and the benefit ('build on earlier results without re-paying') makes 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.

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

The description gives clear context for when to use this tool: when you want earlier scan results and want to avoid re-paying. It also notes it's 'Free to call,' which is a direct usage incentive. It doesn't explicitly name alternative tools, but the mention of 'from agent_history' in the schema parameter description provides a pointer to the sibling history 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 declare readOnlyHint and idempotentHint, so safety is covered. The description adds valuable behavioral detail beyond annotations, such as returning lifetime call count and spend, and clarifying the identification method (API key / wallet / anonymous session). It also notes the tool is free to call, providing extra context.

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

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

The description is a single, well-structured sentence that front-loads the action and purpose. It efficiently conveys the key return items without unnecessary words, and every clause earns its place.

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

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

For a simple, parameterless tool with strong annotations and no output schema, the description fully explains what information is returned (agent_id, authentication type, call count, spend). It is 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?

The tool has zero parameters, which meets the baseline of 4. The description doesn't need to add parameter meaning since there are none, and the schema coverage is trivially 100%.

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: it returns the agent's persistent identity, authentication method, and lifetime usage statistics. The verb 'Returns' is specific and the resource (agent identity) is uniquely identifiable, distinguishing it from sibling security/audit 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 implies that this tool is for getting your own identity, and notes 'Free to call' as a cost-related guideline, but it does not explicitly state when to use it versus alternatives or any exclusion criteria. Usage context is partially clear but not fully developed.

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 safety profile is covered. The description adds valuable behavioral context: the tool costs $5 per call and is intended for after gaps are closed, which informs an agent's decision-making 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 serving a distinct purpose: main function, when to use, alternative, and cost. It is front-loaded and free of fluff.

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

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

Despite annotations providing some context, the tool is complex with 6 parameters and no output schema. The description does not explain what the report contains, how results are returned, or any requirements for the assessment_results array. For an agent to use this correctly, more detail is needed.

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 only 17%, and the description does not compensate. It does not explain parameters like assessment_results, framework, or report_type beyond what the schema's enums and names imply. The agent receives little guidance on how to populate these fields.

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: 'Synthesize findings into an audit-ready compliance report.' It uses a specific verb and resource, and distinguishes itself from siblings by mentioning the engagement stage and alternative tool.

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 guidance is provided: 'Use at the END of an engagement, once gaps are closed.' It also names an alternative: 'run compliance_framework_check instead — it costs less and answers that question directly.' This is clear when-to-use and when-not-to-use.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds useful behavioral context: the cost of the call ($2) and the nature of the output (per-control status). No contradiction with annotations exists.

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

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

The description is two concise sentences plus a cost note. It is front-loaded with the core action and output, and every sentence earns its place without redundancy.

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

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

The description gives a useful high-level output ('per-control status') and usage priority, but it does not explain the required organization_profile structure or how results are returned (no output schema). For a tool with a complex nested input object, this is a moderate gap.

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 only 33% (only previous_scan_id has a description). The description does not explain the framework enum values or the required organization_profile fields (industry, employee_count, etc.). It mentions 'compliance framework' and 'organization' but adds little behind what the schema already shows.

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 'Assess' with a clear resource ('an organization's security posture against a compliance framework') and states the output ('report per-control status'). It also enumerates the supported frameworks and explicitly distinguishes from the sibling tool control_gap_analysis.

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 when-to-use guidance: 'Use this FIRST when asked whether the org is audit-ready' and names the alternative relationship: 'control_gap_analysis builds on its output.' This clearly orients the agent to when this tool is appropriate versus the sibling.

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 and idempotent behavior. The description adds a cost warning ($2 per call) and clarifies that it produces a roadmap with effort estimates, which goes beyond the annotated 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 two sentences covering purpose, usage timing, and cost with no redundant wording.

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

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

No output schema exists, and the description does not specify return fields, pagination, or how constraints affect results. The tool has 5 parameters, most without schema descriptions, so the description leaves significant operational 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 description coverage is only 20% (previous_scan_id only). The description offers no explanation of framework, failing_controls, budget_constraint, or timeline_constraint semantics, so the agent must rely on parameter names and enums 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 that the tool converts unmet compliance controls into a prioritized remediation roadmap with effort estimates, which is a specific verb+resource+output. It also references compliance_framework_check, distinguishing its purpose from that sibling tool.

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 instructs to use this tool after compliance_framework_check and to answer 'what do we fix first', providing clear workflow guidance. It does not explicitly state when not to use it, but the context is clear.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds a cost disclosure ($2 per call) plus what data is exposed, providing useful behavioral context. No contradiction with annotations; it adds value beyond them.

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 with the purpose, use case, and cost — every word earns its place and the key information is front-loaded.

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

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

Given no output schema, the description hints at return contents (breaches and data classes), includes cost and use case, and annotations cover safety. Missing only minor details like rate limits or result structure, but sufficient for a simple check 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?

Only 33% of parameters have schema descriptions, so the description must compensate. It explains check_type via 'email address or domain' and target implicitly, but doesn't detail format constraints or the optional previous_scan_id beyond what the schema already says.

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

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

Description uses specific verb 'Check' with resource 'credential-breach corpora' and explicitly names Have I Been Pwned, clearly distinguishing it from sibling tools like cve_lookup or threat_intel_lookup. It states exactly what is checked (email/domain) and what is returned (breaches, data classes).

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 a clear when-to-use scenario ('Use when assessing account-takeover exposure'), but does not mention exclusions or alternatives. This gives context but stops short of full when-not/alternative guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, covering safety. The description adds the cost of $1 per call, which is critical for decision-making, and specifies the scope of information returned. This goes beyond the annotations without contradicting them.

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 action ('Look up one CVE'), then lists return contents, provides usage guidance, and notes cost. Every sentence carries 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?

For a simple lookup tool with strong annotations and clear input schema, the description is complete. It covers what the tool does, what data it returns, when to use it, and the cost. No output schema exists, but the listed return types (CVSS, affected products, patch availability, references) give the agent enough context to interpret results.

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 50%, with previous_scan_id having a full description in the schema. cve_id is self-evident from the tool name and description ('by identifier') and its pattern is defined in the schema. The description adds no new parameter semantics, but the schema covers the essential details.

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: 'Look up one CVE by identifier' and enumerates the returned data (CVSS score/vector, affected products, patch availability, references). This is a specific verb+resource pairing that distinguishes it from sibling tools like threat_intel_lookup or vuln_prioritize.

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 usage condition: 'Use when a specific CVE ID is already known.' This tells the agent when to invoke it, though it doesn't explicitly state when not to use it or name alternative tools. The condition is enough to guide selection 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 disclose read-only, open-world, and idempotent behavior; the description adds the cost ('Costs $2 per call'), which is a behavioral trait not covered by annotations. 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 that are front-loaded with the purpose. Every clause earns its place: the action, resource, ecosystems, value proposition, and cost. No redundant or fluff 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?

For a tool with a nested source object and no output schema, the description covers the core purpose, supported ecosystems, cost, and typical use case. It does not explain return format, but the lack of output schema reduces that obligation. Adequate for 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 description coverage is 50% (previous_scan_id described in-schema; source not). The description adds meaning by enumerating supported ecosystems (npm, pip, Go, Ruby, Java, Cargo) and clarifying the two input forms (manifest vs https git repo), which maps directly to source.type and source.manifest_type.

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: 'Audit a dependency manifest or https git repo for known-vulnerable packages (trivy).' It names the specific resource (dependency manifest or git repo), the action (audit), and the scope (known-vulnerable packages, with ecosystems listed). This distinguishes it from sibling tools like cve_lookup or vuln_scan_network.

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 explicit contextual guidance: 'The cheapest, highest-signal first step when assessing an unfamiliar repository.' This tells the agent when to use the tool, but it does not explicitly name when not to use it or mention alternative tools.

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

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

The annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description consistently adds 'Passive' and the important cost detail ('Costs $1 per call') beyond annotations. It doesn't contradict annotations, but it doesn't describe the return format or grading scale, so it doesn't reach 5.

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

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

The description is three sentences, front-loaded with the core action, then provides scope, alternative, and cost. Every sentence earns its place with no redundant 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 no output schema, the description covers purpose, scope, behavior, cost, and the main alternative. It does not explain what the 'grade' looks like or how to interpret the result, which is a minor gap for an agent, but the description is still largely complete for invoking 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 50%; the previous_scan_id parameter is well-described in the schema, but the domain parameter has no description. The tool description names 'domain' and the records checked, but doesn't add extra semantics for the parameters beyond what the schema already provides. This is adequate but not compensatory for the coverage gap.

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

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

The description uses a specific verb ('Check') and names the resource ('a domain's DNS security records — SPF, DKIM, DMARC, DNSSEC') and the action ('grade the configuration'). It clearly differentiates from the sibling tool email_security_audit by stating it covers the records themselves rather than full spoofability posture.

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 states when to use this tool versus an alternative: 'Covers the records themselves; for full spoofability posture use email_security_audit.' It also notes the tool is 'Passive' and discloses the cost, giving the agent clear context for deciding when to invoke it.

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 and idempotentHint, so the description adds value by disclosing the specific checks performed (DMARC/SPF/DKIM alignment and policy strength) and the $2 cost. This goes beyond what annotations provide and helps the agent understand what the tool does without contradicting 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 extremely concise with only two sentences. It front-loads the core purpose and includes essential operational context (cost, relationship to sibling tool) without any fluff. Every word 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?

Given the tool's moderate complexity and lack of output schema, the description provides a good high-level overview but has gaps. It does not describe the return format, what include_mx_analysis does, or any details about how the DMARC/SPF/DKIM analysis is presented. The core purpose is clear, but the missing parameter semantics and output behavior make it only minimally complete for an agent to use 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 only 33% (only previous_scan_id is described). The description does not mention or explain any parameters, leaving include_mx_analysis completely unexplained. Since the schema coverage is low, the description should have compensated by explaining parameter meaning, but it does not. Only 'domain' is self-evident from the context.

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

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

The description states the tool's purpose with a specific verb and resource: 'Full email-security posture for a domain: whether mail from it can be spoofed, with DMARC/SPF/DKIM alignment and policy strength.' This is a clear and specific definition that distinguishes it from sibling tools like dns_security_check by explicitly stating it is a 'superset' for the email question.

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 usage context by noting 'A superset of dns_security_check for the email question specifically,' which helps an agent choose this tool over alternatives. It also mentions the $2 per-call cost, which is relevant for decision-making. However, it does not explicitly state when not to use it or name alternatives beyond dns_security_check.

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; the description adds that it only plans and does not gather evidence, and discloses the $1 per call cost. This provides useful behavioral context beyond the annotations, though it doesn't explain why integrations credentials are accepted.

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, front-loaded with purpose, then usage, then exclusions and cost. Every sentence adds value and there is no redundant or vague language.

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 clear purpose, the tool has 4 parameters including a nested integrations object and no output schema. The description does not explain the purpose of integrations (tokens, regions) or what the plan output contains, leaving significant gaps for correct invocation. An agent would not know if integrations are required for certain frameworks or how they affect the plan.

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 only 25% (only previous_scan_id is described). The description mentions 'specific compliance controls' and 'framework' implicitly but does not explain control_ids format, integrations purpose, or how the parameters map to the plan. The integrations object with tokens and regions is entirely unexplained, leaving the agent to guess.

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 'Build' and clearly states the resource: an evidence-collection plan for compliance controls. It distinguishes itself from siblings like control_gap_analysis and audit_report_generate by focusing on planning what artifacts are needed, where they come from, and what makes them sufficient.

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

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

It gives explicit when-to-use ('when preparing for a real audit, after the gaps are known') and a clear when-not ('does not gather evidence for you'). While it doesn't name alternative tools explicitly, it implies the workflow context, which is sufficient for an agent to select it appropriately.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds 'Free to call' and explains the optional filter, providing useful context 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?

A single, front-loaded sentence that conveys purpose, scope, and optionality with no wasted words.

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

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

The tool is simple with one optional parameter, no output schema, and clear annotations. The description provides sufficient context for an agent to understand 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 has one parameter with an enum, but no descriptions. The description compensates by explaining the topic filter and listing several example topics, though it does not enumerate all possible values or add detailed semantics for each.

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

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

The description clearly states the tool returns an FAQ and lists the main topics covered. It uses a specific verb ('Returns') and resource ('AgentAegis FAQ'), distinguishing it from sibling security 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 implies use for general informational queries with an optional topic filter and notes it is free to call, but does not explicitly state when to use it versus alternatives or list exclusions. Context makes it clear it is the go-to help resource.

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 adds valuable context beyond annotations: cost ($3 per call), the nature of the analysis, and the output content. No contradiction exists; it could go further on limitations, but the added details are meaningful.

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 short sentences: purpose, usage guidance, and cost. Front-loaded, every sentence earns its place, and there is no redundancy or filler.

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

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

Covers purpose, usage, output types, and cost, but omits details about required parameters and the environment_context object. With no output schema, the description partially describes returns but leaves much to be inferred. It is adequate for a relatively complex tool but has clear gaps.

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

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

Schema description coverage is only 25%, and the description does not explain key parameters like incident_description, indicators, or environment_context. The phrase 'If all you have is a suspicious IP or domain' indirectly hints at input criteria but does not substitute for param-level guidance. Given low schema coverage, the description must compensate and does not.

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

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

The description uses a specific verb ('classify') and resource ('security incident'), and enumerates concrete outputs (severity, likely category, containment steps, response plan). It also distinguishes from sibling threat_intel_lookup by clarifying when this tool applies ('when something has already happened').

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 states when to use ('Use when something has already happened') and provides a direct alternative with rationale ('If all you have is a suspicious IP or domain, run threat_intel_lookup first — it is cheaper and may settle the question'). This is strong, actionable guidance.

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

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

Annotations declare readOnlyHint and idempotentHint, and the description adds non-contradicting behavioral context: it analyzes caller-provided data, does not connect to an identity provider, and costs $1 per call. This meaningfully supplements the annotations, though it does not describe return format or rate limits.

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

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

The description is three crisp sentences, each adding essential information: the main purpose, the offline behavior/exclusion, and the cost. No filler or redundancy; 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?

Given the moderate complexity, a well-detailed input schema, and strong annotations, the description is largely sufficient. It clarifies the offline, non-connecting nature and cost. A minor gap is the lack of explicit details about the return value, especially since there is no output schema, but the core usage context is complete enough for an agent.

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 50% (previous_scan_id is documented, users is not). The description partially compensates by mentioning 'user or configuration set you supply' and concepts like 'unenrolled accounts' and 'weak factors such as SMS', which map to schema fields. However, it does not provide detailed parameter-level semantics for the users array or previous_scan_id beyond what the schema already offers.

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 ('Assess') and resource ('MFA coverage and factor strength'), and clearly scopes the tool to data the caller supplies. It distinguishes itself from siblings by explicitly stating it does not connect to an identity provider, which is a key differentiator among the audit 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 clear context: use this when you have a user or configuration set to supply, and not when you need live identity provider access ('it does not connect to an identity provider'). It implies an offline-analysis use case but does not explicitly name alternative tools or provide exhaustive when-to-use/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.

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

Annotations already provide readOnlyHint, openWorldHint, and idempotentHint. The description adds significant context by disclosing the $2 per call cost, which is a behavioral trait not captured by the annotations. It does not contradict the annotations, though it could further clarify what happens to the generated policy (e.g., returned inline vs. stored).

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, front-loaded with the core purpose, followed by usage guidance and cost. Every sentence carries essential information with no fluff or redundancy.

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

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

With 7 parameters, 5 required, a nested object, and no output schema, the description is too sparse. It does not explain the return format (beyond 'written security policy'), how customizations influence the output, or how the named parameters are used. The cost and usage triggers are useful, but the overall context is incomplete for an agent to confidently invoke 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 only 14% (only previous_scan_id has a description). The description mentions some policy types (mapping to the enum) but does not explain the meaning or role of other required parameters like organization_name, industry, employee_count, frameworks, or customizations. Given the low coverage, the description should compensate but does not.

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

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

The description clearly states the tool 'generates a tailored written security policy' with specific examples of policy types, and explicitly ties usage to 'control gap' scenarios, distinguishing it from siblings like audit_report_generate. The verb 'generate' and resource 'written security policy' are specific.

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

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

The description provides explicit guidance: 'Use when a control gap specifically calls for documented policy.' This gives a clear trigger condition. However, it does not mention when not to use it or alternative tools, so it falls short of a 5.

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

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

Annotations already declare read-only and idempotent behavior, and the description adds valuable context: it uses Semgrep, supports specific languages, lists vulnerability categories, and discloses a cost of $5 per call. This goes beyond the annotations without contradicting them, though it does not describe the output format or scan result 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 compact and front-loaded with the core purpose, using roughly two sentences. The second sentence about alternatives is somewhat grammatically awkward and could mislead, but all content serves a purpose—including the cost warning—so it remains 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?

Given the moderate complexity of a nested source object, three parameters, and no output schema, the description covers most necessary context: purpose, supported inputs, languages, vulnerability classes, alternatives, and cost. It omits explicit detail on return values and severity_threshold effects, but the annotations and sibling tools (e.g., agent_scan_get) help fill those 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 description coverage is low (33%), and the description partially compensates by clarifying that 'source' accepts either an HTTPS git repo or code snippet, matching the source.type enum. However, it does not explain the severity_threshold behavior or the code/url property specifics, leaving the main input only partially elaborated.

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

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

The description clearly identifies the tool as static analysis for security flaws in source code or git repos, listing specific vulnerability types (injection, unsafe deserialization, etc.) and supported languages. It also distinguishes itself from siblings by explicitly naming secret_scan and dependency_audit for different concerns, making its purpose unambiguous.

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

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

It gives clear when-to-use guidance: static security analysis for a set of weakness classes. It attempts to direct users to alternatives for hardcoded credentials and vulnerable packages, though the phrasing 'For code LOGIC flaws' is confusing since those examples are not logic flaws, slightly weakening the exclusion guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is already known. The description adds valuable behavioral context beyond annotations: it incurs a cost ($5 per call), scans for specific risk categories (exfiltration, prompt-injection sinks, npm hooks, obfuscation), and returns a risk verdict with findings. 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 a single well-structured sentence that front-loads the core action and purpose, then packs in risk categories and the verdict type. Every clause adds information; there is no fluff or redundant repetition of schema field names.

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 complexity (nested source object, paid call, no output schema), the description covers the essential context: what threat model it addresses, the verdict categories, and the cost. It lacks explicit detail on the return structure, but the mention of 'findings' and the verdict provides enough for an agent to understand the outcome. Sibling tools and remaining schema fields fill some 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 description coverage is 50%: the previous_scan_id parameter is well described in the schema, but the required 'source' object has no field descriptions. The description partially compensates by indicating the two source entry modes ('git repo or code'), which maps to the source.type enum, but it does not explain nested fields like url, code, or language. This is adequate but leaves some ambiguity.

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

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

The description uses a specific verb ('Scan') and resource ('MCP server') with a clear objective ('supply-chain risk BEFORE trusting it'). It enumerates concrete risk categories and names the output verdict (PROCEED/CAUTION/BLOCK), distinguishing it from sibling scan tools like sast_scan or secret_scan by focusing on MCP supply-chain trust.

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 implies when to use the tool ('BEFORE trusting an MCP server') and frames it as a pre-trust assessment. It does not explicitly name alternative tools or state when not to use it, but the context strongly suggests it is for evaluating untrusted MCP servers, which is sufficient for most selection decisions.

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 openWorld hints, but the description adds crucial behavioral context: it costs $5 per call, returns a PROCEED/CAUTION/BLOCK verdict, and performs 'hard block' on certain conditions. These details go well beyond the annotations and directly inform the agent's decision-making.

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, information-dense sentence that front-loads the core action and then enumerates risk categories and the verdict. The dash-list format is efficient, though it borders on a run-on. Every clause adds value, and the cost is stated at the end as an important caveat.

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?

This is a medium-complexity tool with a nested source object and no output schema. The description covers the main input types (git repo, SKILL.md), the analysis dimensions, and the output verdict. It lacks a brief example of source construction, but given the schema's enum and the tool's focused purpose, the description is largely 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 covers previous_scan_id with a full description, but source is undocumented. The description partially compensates by mentioning 'git repo or SKILL.md', which aligns with the source.type enum, but it does not explain how to structure the source object (url vs skill_md). With 50% schema coverage, the description adds some meaning but not enough to fully bridge the gap.

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

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

The description clearly states the verb 'Scan' and the resource 'an agent SKILL', with specific scope (git repo or SKILL.md) and a concrete purpose (supply-chain risk). It distinguishes from sibling tools like scan_mcp_plugin by targeting SKILLs specifically.

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

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

The phrase 'BEFORE trusting it' provides explicit timing for use, and the listed checks (prompt-injection, over-broad grants, exfiltration) imply a pre-adoption security review context. It doesn't explicitly name alternatives or exclusions, but the SKILL-specific focus makes the use case clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable context beyond these: it charges $2 per call, performs verification against the issuing provider 'where supported', and implies an external network interaction (openWorldHint is reinforced). No contradictions exist. It does not mention rate limits or output format, but for a read-only scan this is adequate.

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

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

The description is two sentences, front-loaded with the action and scope. The cost note is a single brief clause. Every word adds value; 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?

Given the nested source object, a boolean flag, and a chaining ID, the description covers the core purpose but not the full parameter semantics. No output schema exists, and the description does not hint at what the result contains (e.g., findings list, verification status). The include_history parameter is not explained in either the description or schema, and the source object's field constraints are left vague. While the schema documents previous_scan_id, overall the context is incomplete for an agent to invoke with full confidence.

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 33% (only previous_scan_id documented). The description helps interpret the 'source' parameter by naming the two modes (source code or git repo), which aligns with the schema's type enum. However, it does not explain the structure of source (when to use url vs code), nor the meaning of include_history. The description partially compensates but leaves gaps.

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

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

The description clearly states the tool's function: 'Detect hardcoded credentials, API keys and tokens in source code or an https git repo.' It includes the specific engine (trufflehog) and verification behavior, and explicitly frames the use case as 'did we commit a secret'. This distinguishes it from siblings like sast_scan or credential_check.

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 usage context: 'Use when the question is "did we commit a secret".' It also notes the cost, which is a practical consideration for deciding when to invoke. However, it does not explicitly list alternative tools or when to avoid use, so it stops short of full alternative guidance.

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, open-world, and idempotent behavior. The description adds crucial cost information ($1 per call) and a passivity guarantee ('safe against any host'), which are beyond annotation coverage. It doesn't address error handling or output format, but the critical behaviors 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.

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

Two concise sentences front-load the primary purpose, followed by safety and cost. No wasted words, each sentence adds distinct 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 description gives high-level purpose, safety, and cost, but lacks information about return format or how to interpret results, especially with no output schema. It also doesn't mention chaining via previous_scan_id. This leaves some ambiguity for the agent, but the core purpose is clear, so a mid-range score.

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 description does not explain the hostname, port, or previous_scan_id parameters. While 'domain' implies hostname, the schema coverage is only 33% (previous_scan_id already described) and the description fails to compensate for the undocumented port parameter or clarify default behavior. A score of 2 reflects minimal semantic addition.

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 audits a domain's TLS configuration, listing specific aspects (certificates, protocols, ciphers, weaknesses). This distinguishes it from sibling audit tools like dns_security_check or email_security_audit by its focus on TLS.

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 that this is a passive, safe read operation and costs $1 per call, guiding when to use it. However, it doesn't explicitly discuss alternatives or when not to use it, so not a 5.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses significant behavioral details: monetary cost per call ($2) and the statistically noisy nature of reputation hits for benign infrastructure. These are meaningful operational traits not captured by annotations, though it does not cover response format or rate limits.

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

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

Three sentences, front-loaded with the core purpose. Each sentence provides distinct value: what it does, cost/positioning, and a crucial caveat. No redundant phrasing.

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

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

The description explains purpose, cost, and interpretation caveats, which are essential. However, with no output schema, it omits what the response structure looks like (e.g., source-specific verdicts, scores, timestamps), which an agent may need to interpret or act on results. It also misses the fact that more indicator types than IP/domain are accepted.

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 has 3 parameters with only 33% description coverage (only previous_scan_id gets a description). The tool description says 'for an IP or domain', but the indicator_type enum includes url and hashes, so it under-specifies accepted types and could mislead the agent into thinking only IP/domain are supported. It also does not explain the previous_scan_id parameter at all.

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+resource structure: 'Reputation and indicator lookup for an IP or domain across AbuseIPDB, AlienVault OTX and abuse.ch.' It clearly distinguishes from siblings like cve_lookup or dns_security_check by focusing on threat reputation across named sources. The phrase 'cheapest way to check whether an indicator is known-bad' further clarifies its role.

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 ('cheapest way to check whether an indicator is known-bad') and includes important cautions about interpreting results (CDN/cloud/payment infrastructure false positives). However, it does not explicitly name alternatives or state when not to use it, so it lacks explicit exclusion criteria.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses a $3 per-call cost and explains that the tool aggregates multiple checks into a single decision with reasons. This adds meaningful behavioral context beyond what annotations 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 sentences deliver purpose, alternatives, rationale, and cost without redundancy. Information is front-loaded with the verdict type and use case.

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 no output schema, the description adequately explains what the tool does, what inputs it accepts, and its cost. It lacks explicit detail on the exact return format (e.g., JSON structure of reasons), but the core functionality is well covered.

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 detailed descriptions (endpoint accepts URL or domain; previous_scan_id is an optional lineage parent). The tool description adds only minor context (endpoint being called or paid), so it doesn't significantly enhance 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 states the tool produces a composite trust verdict (PROCEED/CAUTION/BLOCK) for an endpoint, combining multiple security checks. It clearly distinguishes itself from sibling tools by naming them and positioning this as a consolidated alternative.

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

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

Explicitly instructs to prefer this tool over running ssl_tls_audit, dns_security_check, and threat_intel_lookup separately, citing lower cost and a decision-oriented output. This provides clear when-to-use guidance and names alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable context: it only analyzes supplied findings, never performs discovery, and costs $1 per call. This goes beyond the annotations and provides practical operational details.

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

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

The description is three sentences, each adding value: purpose, scope limitation, and cost. No fluff, and the main purpose is front-loaded.

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

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

With no output schema and nested input parameters, the description is somewhat sparse. It mentions grouping into remediation actions but does not explain return format, nor does it cover business_context or previous_scan_id. The core behavior is described, but the full context needed for a complex call is incomplete.

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 only 33% (only previous_scan_id is described). The description loosely references 'findings' and 'business impact' but does not explain the required structure of the findings array or business_context object, nor does it mention previous_scan_id. It fails to compensate for the low schema coverage.

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 specific verbs 'Rank' and 'group' to describe the tool's function on vulnerabilities the user already has. It explicitly differentiates from sibling tools like vuln_scan_network by stating 'it discovers nothing on its own', making the purpose distinct.

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 implies when to use the tool (after vulnerabilities are known) and provides a when-not by stating it discovers nothing on its own. It does not explicitly name alternative tools, but the context is clear enough to guide selection.

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 critical behavioral traits beyond annotations: 'SENDS REAL TRAFFIC to the target and may trigger intrusion detection,' the cost of $3, and the async option. These significantly inform the agent about real-world impact, which annotations only partially cover.

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 long, front-loaded with purpose, and every sentence adds value: purpose, safety warning, and async/cost. No redundant words; all information is necessary.

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

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

Given no output schema and moderate complexity, the description covers purpose, authorization, real-traffic warning, cost, and async behavior. However, it omits details on scan_type semantics and port_range, which are needed for smooth invocation. This is a notable but not fatal gap.

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

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

Schema coverage is only 20%, so the description carries more burden. It clarifies target as 'IP or domain' and async as returning a job_id, but leaves required scan_type enum values (quick/standard/deep) and port_range format unexplained. The description adds some meaning but does not fully compensate for the low coverage.

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 'Discover open ports, running services and known vulnerabilities on an IP or domain (nmap),' providing a specific verb and resource. The parenthetical '(nmap)' distinguishes it from siblings like vuln_scan_web_app, making the tool's scope immediately clear.

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 explicit authorization guidance: 'only run against hosts the caller owns or is explicitly authorized to test, and confirm that first.' It also mentions async usage for non-blocking execution, but does not explicitly contrast against alternative tools like vuln_scan_web_app, though this is implied by 'nmap'.

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 goes well beyond annotations by explicitly warning 'SENDS REAL TRAFFIC' and 'authorized targets only, confirm before calling.' It also discloses cost and async behavior, giving the agent critical side-effect information that annotations (readOnlyHint=false, openWorldHint=true) only hint at.

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

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

Three tight sentences: purpose, safety warning, and async/cost. No filler, front-loaded with the core function and critical warnings. Every sentence carries necessary 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 description covers purpose, safety, cost, and async behavior, but with no output schema it omits what the final scan results look like. It also leaves key parameters (scan_depth, authentication) unexplained. The provided warnings and async tip are valuable, but the tool remains under-specified for reliable invocation in varied scenarios.

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

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

With schema description coverage at only 17%, the description must compensate, but it only explains async (via 'Pass async:true to get a job_id to poll instead of blocking'). It does not clarify target_url, scan_depth, exclude_paths, or authentication, leaving the agent to guess meanings of these required/nested parameters.

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

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

The description clearly states the tool scans a web application for OWASP Top 10 issues and known CVEs using Nuclei. The verb 'scan' with specific resources ('web application', 'OWASP Top 10', 'known CVEs') distinguishes it from siblings like vuln_scan_network and sast_scan.

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 context: targets a web application, sends real traffic, requires authorization, and offers an async mode. However, it does not explicitly compare to alternatives (e.g., when to use sast_scan or vuln_scan_network), so it stops short of full exclusion guidance.

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