AgentAegis

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

No annotations are present, so the description must fully disclose behavioral traits. It only says 'Audit user access against least-privilege,' with no indication of whether the tool modifies data, requires authentication, or produces output. This is extremely insufficient.

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 with no structure. While concise, it is under-specified and lacks the detail needed for effective tool selection.

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 has 4 parameters, no output schema, and many sibling tools, the one-sentence description is completely inadequate. It fails to provide any context for how the tool fits into a workflow or what results 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 description coverage is only 25% (one param documented). The description does not explain the meaning or purpose of any parameter, leaving the agent to guess how to populate the 'users' array or use 'admin_roles' and 'sensitive_permissions.'

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 ('Audit') and resource ('user access') with a criterion ('least-privilege'), giving a clear sense of the tool's purpose. However, it does not differentiate from sibling tools like audit_report_generate or compliance_framework_check, which are also audit-related.

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

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

No guidance is provided on when to use this tool versus alternatives. The sibling list includes many security audit tools, but the description lacks any context for choosing this one.

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?

No annotations are provided, so the description carries full burden. It discloses that the tool is free to call and returns specific data, implying a read-only, non-destructive operation. However, it does not explicitly state idempotency or lack of side effects, which would be beneficial for a zero-param tool.

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 consists of two concise sentences. The first sentence lists the return values, and the second adds the free-to-call trait. No wasted words; front-loaded with key purpose.

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 tool with no output schema, the description provides a complete list of what is returned (prepaid balance, monthly limit, current usage, tool affordability breakdown). No additional context (e.g., pagination, errors) is needed given the simplicity.

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

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

The input schema has no parameters (coverage 100%), so the description does not need to add parameter details. The baseline for zero parameters is 4, and the description meets this standard without superfluous information.

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 the calling API key's prepaid balance, monthly limit, current usage, and tool affordability. It uses a specific verb ('Returns') and resource ('calling API key's balance'), and distinguishes itself from sibling security audit tools which have different purposes.

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

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

The description implies usage for checking account balance/usage and explicitly states it is free to call. While it does not provide when-not-to-use or alternative references, the sibling tools are all security-related, so the tool's unique function is clear. A slight gap exists in not excluding scenarios like when balance is irrelevant.

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?

No annotations provided. The description states 'Free to call' indicating no side effects or auth needed, and lists output fields. For a read-only history tool, this is sufficiently transparent.

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 purpose and include key details. No unnecessary 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?

Despite no output schema, the description lists return fields (scan_id, tool, target, status, time) which is sufficient for this simple list tool. No missing critical 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?

Schema coverage is 100% with descriptions for all 4 parameters. The description adds value by stating the default limit (25) and clarifying 'since' as ISO-8601, which goes beyond the schema.

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

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

The description clearly states the tool lists recent scans with specific fields (scan_id, tool, target, status, time) and its purpose for retrieval or chaining. This differentiates it from siblings like agent_scan_get.

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

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

The description implies usage for reviewing history and mentions 'Free to call', but does not explicitly contrast with alternatives like agent_scan_get. However, the context signals include siblings that likely have distinct purposes.

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?

No annotations are provided, so the description carries the burden. It states the tool is for retrieval and free, but doesn't mention auth requirements, error handling (e.g., if scan_id not found), or any side effects. However, for a read-only retrieval tool, it is reasonably transparent.

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

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

Two sentences, no redundant words, front-loaded with the action and key details. Every sentence 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 simple retrieval tool with no output schema, the description covers purpose, parameter use, and benefit. It doesn't explain return format or error conditions, but these are often implicit for such tools. It's 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 coverage is 100% with good descriptions. The description adds no additional parameter details beyond the schema, but it does tie the include_full_output parameter to the 'stored full output' mentioned. 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 it retrieves a prior scan by scan_id, including full output, with a specific benefit. It distinguishes from sibling tools like agent_history and various scan tools because it's for retrieving existing results.

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 when to use (to build on earlier results without re-paying) and that it's free. It doesn't explicitly state when not to use or list alternatives, but the context is fairly 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?

With no annotations provided, the description fully bears the burden of behavioral disclosure. It explains the tool returns identity, identification method, and call count+spend, and emphasizes it is free to call, indicating no cost or destructive side effects. This is adequate transparency for a simple read-only tool.

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

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

The description is a single, well-structured sentence that front-loads the main purpose and includes key details. Every phrase earns its place with no unnecessary 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?

For a zero-parameter, no-output-schema tool, the description is complete enough. It specifies what is returned and that the call is free. Minor omissions like rate limits or authorization details are acceptable for this simple 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?

The tool has zero parameters, so schema description coverage is 100% by default. Per rules, baseline is 4. The description adds no parameter-specific information, but none is needed.

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 'Returns' followed by the specific resource: persistent agent identity, identification method, call count, and spend. It distinguishes itself from sibling tools like 'agent_history' and 'account_balance' by focusing on identity and lifetime stats.

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 mentions 'Free to call' implying it's safe to use without cost, but provides no explicit guidance on when to use this tool versus alternatives like 'agent_history' or 'account_balance'. No exclusions or prerequisites are mentioned.

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?

No annotations are provided, and the description only states the tool generates reports. It does not disclose whether the tool is read-only, what side effects occur, or output characteristics, which is insufficient for a generative tool.

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 short sentence, but it is under-specified for a tool with six parameters. It lacks necessary detail rather than being appropriately 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?

Given the complexity of the input schema (6 parameters, nested array) and no output schema, a single sentence is grossly insufficient. Missing details like report format, handling of assessment_results, and interpretation of framework and report_type.

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 description coverage is only 17%, and the tool description adds no contextual meaning to any parameter. It does not explain enum values like framework or report_type, nor the structure of assessment_results.

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 compliance reports, but it does not distinguish from sibling tools like 'compliance_framework_check' or 'policy_generate', which have similar audit-related purposes.

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

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

The description provides no guidance on when to use this tool versus alternatives. No prerequisites, conditions, or exclusions are mentioned.

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

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

With no annotations, the description must disclose behavioral traits. It only states the purpose and does not mention whether the operation is read-only, any side effects, authentication requirements, or rate limits. The description is insufficient for 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 a single, well-structured sentence that front-loads the verb and resource. No extraneous information; 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 complexity (3 parameters, including a nested object with many fields) and no output schema, the description is incomplete. It does not explain what the assessment results look like, how to interpret them, or details about the organization_profile fields. The agent lacks essential context for effective use.

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%, with only previous_scan_id having a description. The description does not explain the organization_profile nested object or its required fields beyond their names. The enum for framework is self-explanatory but not 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 states the tool's purpose: assessing security posture against specific compliance frameworks (SOC 2, ISO 27001, HIPAA, PCI-DSS, NIST CSF). The verb 'Assess' and the resource 'security posture' are specific, but the description does not differentiate from similar tools like control_gap_analysis or audit_report_generate.

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

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

The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or limitations. The agent is left without context for appropriate usage.

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?

With no annotations, the description carries full burden for behavioral disclosure. It only hints at output (remediation roadmap) but fails to state whether the tool is read-only, requires authentication, or has side effects. The 'deep-dive analysis' label is implicit but not explicit.

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

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

The description is a single 10-word sentence, which is concise but lacks structure. It front-loads key terms but omits necessary details, making it minimally adequate.

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 (5 parameters, no output schema), the description is incomplete. It does not explain the return format or how the analysis is performed, leaving a significant gap for the agent to choose 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?

Only 20% of parameters have descriptions in the schema, and the tool description adds no additional meaning for any parameter. The agent must rely on parameter names and enums, which is insufficient for a complex analysis tool.

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 a specific verb-noun pair ('deep-dive analysis of compliance control gaps') and distinguishes itself from siblings like compliance_framework_check by emphasizing a remediation roadmap, which is a distinct output.

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

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

No explicit guidance on when to use this tool versus alternatives. The description does not mention prerequisites or when not to use it, leaving the agent to infer from the name alone.

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

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

No annotations exist, so description must fully describe behavior. It omits any side effects (e.g., external API calls to HIBP, potential rate limits), data sensitivity, or idempotency. Only states the basic check action.

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?

Extremely concise at one sentence, but lacks structure or emphasis. No breaks, headings, or prioritization of key info.

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, description should explain expected results (e.g., breach found, no breach, error) and workflow integration. It does not, leaving agent guessing about return format or behavior.

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

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

Schema coverage is low (33%) with only previous_scan_id having description. The tool description adds no parameter details, e.g., format for target or that check_type is email or domain. With low schema coverage, 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's verb (Check) and resource (email/domain) with context (in breach databases via HIBP). It distinguishes from sibling tools focused on other security checks like CVE lookup or DNS audit.

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

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

No guidance on when to use vs alternatives. The description only states what it does without scenarios, prerequisites, or exclusions.

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

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

No annotations are provided, so the description must disclose behavioral traits. It implies a read-only lookup but does not mention safety, authorization, rate limits, or side effects. The description lacks necessary transparency for a standalone tool.

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 short sentence, concise and to the point. However, it could benefit from a slightly more structured format, e.g., listing inputs or outputs explicitly.

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

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

No output schema exists, so the description should compensate by explaining return values. It lists 'details, CVSS scores, and patches' but is vague. Given the complexity (2 params, potential chaining via previous_scan_id), additional context 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 50%, with only previous_scan_id having a description. The tool description adds meaning by stating the purpose of cve_id implicitly, but does not provide format details beyond the schema pattern. Previous_scan_id is not mentioned in the description, leaving its purpose ambiguous.

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 verb ('look up'), resource ('CVE'), and expected outputs ('details, CVSS scores, and patches'), making it distinct from sibling tools like threat_intel_lookup.

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

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

No guidance on when to use this tool versus alternatives (e.g., threat_intel_lookup). No conditions, prerequisites, or context for invocation.

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?

With no annotations, the description must carry the burden of behavioral disclosure, but it omits any mention of side effects (e.g., whether it performs network calls, modifies files, or requires permissions). The verb 'audit' implies a read-only operation, but this is not explicit.

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

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

The description is a single sentence with no wasted words. However, it could be structured to include more detail about the source parameter without losing conciseness.

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 complex nested input schema and absence of an output schema, the description is incomplete. It lacks elaboration on how to specify source (git_repo vs manifest), what the tool returns, and how previous_scan_id affects the workflow.

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 only lists ecosystems, which partially covers the possible values for manifest_type, but does not explain the source object's structure or the optional previous_scan_id. The schema has 50% description coverage, and the tool description 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 'Audit dependencies for known vulnerabilities' clearly states the verb 'audit' and the resource 'dependencies', and lists six supported ecosystems (npm, pip, Go, Ruby, Java, Cargo), which distinguishes it from sibling tools like sast_scan or secret_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 provides no guidance on when to use this tool versus alternatives such as sast_scan or vuln_scan_network. It does not mention prerequisites, limitations, or scenarios where 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?

With no annotations, the description carries full burden. It only lists what is checked but does not disclose behavior such as whether the tool is read-only, returns detailed reports, or any potential side effects. Minimal insight beyond the tool's name.

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, clear sentence with no filler. Every word earn its place, and it is front-loaded with the purpose. Excellent conciseness.

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 no annotations, the description is too bare. It does not explain what the output looks like, any prerequisites, or how to interpret results. For a tool that might return complex data, this is insufficient.

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% (only previous_scan_id has a description). The description does not explain the domain parameter or how to use it, nor does it add meaning to either parameter. Baseline is low due to incomplete schema 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 'Check DNS security (SPF, DKIM, DMARC, DNSSEC).' It uses a specific verb 'Check' and specifies the exact DNS security components, distinguishing it from sibling tools like email_security_audit or ssl_tls_audit.

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

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

No explicit when-to-use or when-not-to-use guidance is provided. The purpose is clear, but no context is given about when to prefer this over alternatives like email_security_audit or threat_intel_lookup. Usage is implied but not spelled out.

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?

No annotations are provided, so the description carries full burden. It does not disclose behavioral traits such as whether the tool performs read-only analysis, what checks it performs, or any side effects.

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

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

The description is overly brief (4 words) and fails to provide necessary detail. While concise, it sacrifices informativeness.

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 three parameters, no output schema, and no annotations, the description is completely inadequate. It does not explain what the tool returns or any prerequisites.

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%). The description adds no meaning beyond the schema; it does not explain parameters like 'domain' or 'include_mx_analysis'.

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 'Comprehensive email security audit' is vague. It does not specify what aspects of email security are audited (e.g., SPF, DKIM, DMARC) and fails to distinguish from siblings like dns_security_check or ssl_tls_audit.

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

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

No guidance is provided on when to use this tool versus alternatives. With many audit-related siblings, the description lacks context for appropriate usage.

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?

With no annotations, the description is the sole source of behavioral info. It does not disclose side effects, authorization needs, rate limits, or whether the plan is persisted or generated on the fly. For a tool that produces output, this is insufficient.

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

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

The single sentence is concise and front-loaded, clearly stating the core purpose. However, it could benefit from additional structure to cover more details without losing brevity.

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 (4 parameters, nested objects, no output schema, 25% schema coverage), the description is grossly insufficient. It omits what the plan looks like, how it is returned, whether integrations are optional, and the meaning of the output. A complete description would need to address these 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% (only 'previous_scan_id' has a description). The description adds no meaning to the 'framework', 'control_ids', or 'integrations' parameters, which include many fields without documentation. The description does not 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 'Generate evidence collection plans for compliance controls' uses a specific verb ('Generate') and names the resource ('evidence collection plans for compliance controls'), clearly distinguishing it from sibling tools like control_gap_analysis or audit_report_generate.

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

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

No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or exclusions. The description gives no context for selecting this tool over others in the sibling list.

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

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

No annotations are provided, so the description carries full burden. It states 'Free to call,' hinting at no cost or rate limiting, but lacks explicit read-only or non-destructive declarations. More detail about response format would improve 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 a single sentence with efficient bullet-like listing of topics, immediately conveying purpose. No unnecessary 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 help tool with one optional parameter, the description covers available topics and hints at cost. It does not specify output format (e.g., plain text, JSON), but the tool's simple nature makes this acceptable. Sibling tools provide clear differentiation.

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

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

Schema description coverage is 0%, but the description adds valuable context by listing the specific FAQ categories that correspond to the enum values, clarifying what the topic filter does.

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 the AgentAegis FAQ, listing specific categories. It distinguishes itself from sibling security audit tools by providing general documentation access.

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 indicates optional topic filter and that the call is free, implying no negative side effects. However, it does not explicitly exclude scenarios or mention alternatives, though siblings are unrelated.

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?

With no annotations, the description carries full burden but fails to disclose behavioral traits such as whether it modifies state, required permissions, or output format. 'Classify and respond' implies action but lacks specifics.

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 brief but underspecified. It does not earn its place as it fails to provide necessary context, making it more of a placeholder than a concise, informative statement.

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 (4 parameters including nested objects, no output schema), the description is woefully incomplete. It lacks details on return values, side effects, or workflow integration.

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% (previous_scan_id only). The description adds no explanation for any parameter, leaving agents to guess the meaning of complex nested objects like indicators and environment_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 classifies and responds to security incidents, which is a clear verb+resource but lacks specificity to distinguish it from sibling tools like threat_intel_lookup or evidence_collect.

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

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

No guidance on when to use this tool versus alternatives, nor any prerequisites or context. The description is too vague to help an agent decide 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?

With no annotations, the description must disclose all behavioral traits, but it only says 'Assess MFA coverage and strength.' It does not clarify that the tool expects an input array of users, nor does it indicate whether the assessment is read-only, or what happens to the data. The description lacks critical behavioral context.

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

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

The description is extremely short (three words), which is concise but under-specified. It does not earn its place because it omits essential details like input format, output, and behavior, making it insufficiently informative.

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 no output schema, so the description should explain return values or the nature of the assessment. It does not. For a tool assessing MFA coverage, the description should mention what the output looks like (e.g., a report, score, or derived findings), which is 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 50% (only previous_scan_id has a description). The description 'Assess MFA coverage and strength' does not explain the users parameter or its structure, failing to add meaning beyond the schema. The description does not compensate for the missing parameter 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 'Assess MFA coverage and strength' uses a specific verb ('Assess') and clearly identifies the resource ('MFA coverage and strength'), distinguishing it from sibling tools like credential_check or ssl_tls_audit.

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

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

The description provides no guidance on when to use this tool versus alternatives such as access_review or compliance_framework_check. There are no explicit context, exclusions, or mentions of 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?

No annotations are provided, so the description carries full burden. It does not disclose any behavioral traits such as side effects, authentication requirements, or rate limits. The tool likely does not mutate data, but this is not stated.

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

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

The description is a single sentence, very concise. However, it is under-specified, lacking details that would justify the conciseness. It is not front-loaded with key 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?

Given the tool has 7 parameters, 5 required, a nested object, and no output schema, the description is insufficient. It does not describe the output format, how policies are tailored, or any prerequisites.

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?

Description does not explain any parameters beyond what the schema provides. With schema description coverage at only 14%, the description should compensate by clarifying parameter roles, but it 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 it generates tailored security policy documents, specifying the resource (policy documents) and qualifier (tailored). However, it does not differentiate from sibling tools like audit_report_generate, which could be confused.

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

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

No guidance on when to use this tool versus alternatives. The description only states what the tool does, not when it should be invoked or when to avoid 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?

No annotations are provided, so the description carries the full burden of disclosure. It states the tool performs static analysis but does not clarify whether it is read-only, destructive, requires authentication, or has rate limits. The behavioral traits are under-specified.

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 very concise—one sentence plus a language list. It is front-loaded but lacks structure. It could be more efficient by including additional context without increasing length significantly.

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 (3 parameters, nested source object, no output schema), the description is incomplete. It does not mention output format, scan duration, or how results are returned. Critical context for agent decision-making is 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 description coverage is only 33% (only previous_scan_id has a description). The description adds no information about the required 'source' parameter or its nested fields (url, code, type, language). It does not 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 the tool performs static analysis for security vulnerabilities and lists supported languages (Python, JS/TS, Java, Go, Ruby, PHP, C/C++). This specific verb+resource combination distinguishes it from sibling tools like secret_scan or dns_security_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 implies usage for security vulnerability scanning but lacks explicit guidance on when to use this tool versus alternatives, such as secret_scan or vuln_scan_network. No prerequisites or exclusions are mentioned.

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

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

No annotations provided, so description must disclose behavioral traits. It only says 'detect' (read operation assumed), but does not clarify whether it modifies state, requires authentication, or how results are returned.

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 sentence is concise but lacks structure; no sections or examples. Under-specified given the tool's complexity (nested parameters, multiple options).

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 and no explanation of return values. Does not explain differences between git_repo and code_snippet, or how include_history affects behavior. Incomplete for effective use.

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 documented). The description adds no information about the source object structure or include_history parameter, 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?

Description clearly states the core action: detecting hardcoded secrets in source code. It is specific and distinguishes from siblings like sast_scan (static analysis) or credential_check (credential validation), though not explicitly differentiated.

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

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

No guidance on when to use this tool vs. alternatives (e.g., credential_check, sast_scan). No mention of prerequisites or context for 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?

No annotations are provided, so the description must disclose behavioral traits. It only states the tool audits, but does not mention if it makes network calls, is read-only, or any side effects.

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

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

The description is a single sentence with no wasted words, but it lacks structured details like bullet points that could improve clarity.

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 no annotations, the description is too brief. It does not explain what the audit returns, what checks are performed, or any success/failure conditions.

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% (previous_scan_id has a description). The description adds no information about hostname or port, failing to 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 the action 'audit' and the resource 'SSL/TLS configuration for a domain', distinguishing it from sibling tools like email_security_audit or dns_security_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?

No guidance on when to use this tool vs. alternatives like credential_check or cve_lookup. Lacks indication of prerequisites or 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?

With no annotations, the description carries full burden. It only says 'lookup', implying read-only, but provides no details on behavioral traits such as rate limits, authentication requirements, error handling, or result format. Critical context for a security tool is missing.

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 with no unnecessary words, which is efficient. However, its brevity sacrifices important details, making it slightly under-specified for the complexity of the 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?

Given no output schema, no annotations, and 3 parameters with low schema coverage, the description is incomplete. It does not explain return values, pagination, error cases, or how to interpret results. A security tool like this needs more context for effective use.

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 adds no parameter specifics. It does not clarify valid values for 'indicator' format or 'indicator_type' enumeration beyond what the enum provides, nor does it explain the optional 'previous_scan_id' parameter's purpose.

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 'IOC lookup against threat intel feeds', specifying the action (lookup) and resource (threat intel feeds). It distinguishes from siblings like 'cve_lookup' and 'credential_check', though the abbreviation 'IOC' may require inference.

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

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

No guidance on when or when not to use the tool. No mention of alternatives among the many sibling security tools, leaving agents to guess the appropriate context (e.g., when to choose this over 'cve_lookup' or '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?

With no annotations, the description carries full burden. It discloses the tool is a composite analysis (not a mutation) and lists the checks performed. It does not explicitly state it is read-only or safe, but the verdict output implies no side effects. The behavioral traits are adequately described.

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

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

The description is a single, front-loaded sentence that efficiently conveys the tool's purpose, output, and inputs. Every part is meaningful 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?

Given the tool's complexity (composite analysis of multiple security checks), no output schema, and no annotations, the description provides sufficient context about what it evaluates and returns. It could mention the verdict format explicitly, but the overall completeness is high.

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 both parameters having descriptions. The tool description adds no additional meaning beyond what the schema already provides for the parameters. 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 clearly states the tool returns a composite trust verdict (PROCEED/CAUTION/BLOCK) for an endpoint, listing the combined factors (TLS, DNS, threat intel, domain age). This distinguishes it from sibling tools that perform individual checks (e.g., dns_security_check, ssl_tls_audit).

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 says the tool is for when 'an agent is about to call or pay' an endpoint, providing clear usage context. However, it does not mention when not to use or name alternatives among the sibling tools, though the composite nature implies when individual checks are insufficient.

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?

Without annotations, the description must disclose behavioral traits but only states the prioritization criteria. It doesn't mention side effects, authentication needs, or return value 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?

A single, front-loaded sentence efficiently conveys the core purpose. No wasted words, though it could benefit from slight expansion.

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 complexity (nested objects, no output schema, no annotations), the description is insufficient. It omits return values, prerequisites, and behavioral 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?

Schema coverage is only 33%, and the description adds no parameter details. The schema is self-explanatory for 'findings' and 'business_context', but the description should 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 the tool prioritizes vulnerabilities using exploitability and business impact. It provides a specific verb and resource, but lacks differentiation from sibling tools like cve_lookup or vuln_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?

No guidance on when to use this tool versus alternatives. No context like 'use after scanning' or exclusions, leaving the agent to infer usage.

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?

With no annotations, the description should disclose behavioral traits. It does not mention whether scans are destructive, require permissions, or produce output. The description is too brief.

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 (one sentence) but overly brief given the tool's complexity. It does not front-load key information or structure 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?

With 5 parameters, no output schema, and no annotations, the description is inadequate. It does not mention async behavior, scan depth, or result format, making it incomplete for correct 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 only 20% (only 'previous_scan_id' has description). The description does not explain the meanings of 'target', 'scan_type', 'port_range', or 'async', so the agent lacks crucial usage 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 scans IP/domain for open ports, services, and vulnerabilities. However, it does not distinguish from the sibling 'vuln_scan_web_app', which likely has a different focus.

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

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

No guidance on when to use this tool versus alternatives like 'vuln_scan_web_app' or 'ssl_tls_audit'. No context about prerequisites or exclusions.

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

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

With no annotations, the description must fully disclose behavior. It only says 'scan...for vulnerabilities,' omitting critical details such as whether the tool is destructive, potential performance impact, authentication needs, or that it supports async operation (as suggested by the input schema). The agent is left uninformed about side effects or operational constraints.

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 with no fluff, but it sacrifices necessary detail for brevity. It could be expanded without becoming verbose, so it earns an average score for conciseness.

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 6 parameters, no output schema, and no annotations, the description is severely incomplete. It omits key context about scan depth, authentication setup, exclude paths, async behavior, and return values, making it insufficient for an agent to use effectively.

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 17% (only previous_scan_id has a description), and the tool description adds nothing about parameters. With 6 parameters including complex ones like authentication (nested object), the agent has no semantic guidance beyond the bare schema names and types.

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 it scans a web app for OWASP Top 10 vulnerabilities, distinguishing it from sibling tools like sast_scan (static analysis) or secret_scan (secret detection). The verb 'scan' and resource 'web app' are specific, though it could be more explicit about the dynamic nature.

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

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

No guidance is provided on when to use this tool versus alternatives like sast_scan or vuln_scan_network. There is no mention of prerequisites, limitations, or exclusions, leaving the agent to guess 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.