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

The annotations already cover read-only, idempotent, non-destructive behavior. The description adds useful behavioral context beyond that by naming the specific checks performed, the OSV.dev data source, and the 'direct dependencies' scope, which clarifies that transitive dependencies are not the focus. 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 tight and front-loaded: the opening sentence states the purpose and scope, followed by a minimal Args block. There is no filler or repetition of schema details, and 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?

With a single optional parameter, rich annotations, and an output schema available, the description covers everything needed for correct invocation. It explains what the tool checks, the dependency scope, and the path semantics without over-explaining return values that the output schema already documents.

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%, so the description must clarify the only parameter, path. It does: 'Project root. Defaults to the client's workspace root.' This resolves the schema's opaque default null and gives the agent enough semantic grounding to invoke the tool correctly.

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

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

States a specific verb ('check') and resource ('direct npm/PyPI dependencies'), and enumerates the exact threat categories it covers: hallucinated packages, typosquats, suspiciously new packages, and known vulnerabilities via OSV.dev. This scope clearly differentiates it from broader siblings like scan_project without needing to inspect them.

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 context via 'direct npm/PyPI dependencies' and the optional path argument, but it never explicitly states when to prefer this tool over siblings like scan_project or scan_snippet. There are no exclusions or alternative routing guidance, so the agent must infer applicability from the scope wording 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?

Annotations provide idempotentHint=true, readOnlyHint=false, and destructiveHint=false, so the agent already knows it writes but is safe to call repeatedly. The description adds useful context beyond those: it states the default output location (<project>/.shipsafe/) and that it is automatically git-ignored, plus describes the HTML report's interactive features. It does not describe error cases (e.g., missing scan) but 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 compact and well-structured: purpose sentence, a bullet on HTML report features, a note on default location, then a concise 'Args' list. It is front-loaded with the primary action, and every sentence adds value. 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?

For a report generation tool, the description covers the core behavior (what it writes, where it writes, available formats) and the output schema exists to describe the return value. It does not explicitly mention prerequisites (e.g., that a scan must have been run) but the phrase 'for the latest scan' plus the sibling scan_project makes that inference reasonable. Missing details like error handling are minor given the output schema and the tool's straightforward nature.

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%, so the description must carry the full parameter explanation. It does: it explains each argument ('format' with enumerated values and their meaning, 'path' as project root with a default, 'output' as an explicit file path). This adds meaning far beyond the bare schema types and defaults, fully compensating for the lack of schema descriptions.

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

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

The description opens with a clear verb+resource: 'Write a shareable report for the latest scan.' It specifies the output artifact and its key features (score ring, severity filters, copy-fix button), and the sibling context (scan_project, list_findings, etc.) shows this tool is distinct because it generates a report rather than performing analysis. The purpose is unambiguous and not a tautology.

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

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

The description implies it should be used after a scan by saying 'for the latest scan,' but it does not explicitly state when to use it versus alternatives, nor does it list any exclusions (e.g., 'use list_findings for raw findings'). It does explain the format options and defaults, which helps the agent decide, but lacks explicit routing or when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds little behavioral detail beyond the purpose statement; 'full details' describes the output rather than disclosing behaviors such as auth requirements, errors, or pagination. There is 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 with no wasted words. The purpose is front-loaded, and the only parameter is documented in a compact, scannable format.

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 one-parameter getter with an output schema and read-only annotations, the description covers the one missing invocation detail: where to obtain finding_id and what format it takes. Nothing else is required for an agent to call 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?

Schema description coverage is 0%, so the description carries full responsibility for parameter meaning. It defines finding_id as the ID from scan_project / list_findings and provides a concrete example format (SS-3F9A2C1), which is exactly what an agent needs to supply the required parameter correctly.

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

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

The description states a specific verb and resource: retrieving full details for one finding, and enumerates content categories (impact, fix guidance, code context, references). It clearly distinguishes itself from sibling list-oriented tools by emphasizing 'one finding' and by referencing scan_project / list_findings as the source of the ID.

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 usage context by noting that finding_id comes from scan_project / list_findings, implying the tool is used after those tools. It does not explicitly list exclusions or alternatives, but the singular scope and the referenced parent tools make the intended workflow 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, so safety is covered. The description adds valuable behavioral context: the operation applies to the latest scan, path defaults to the most recently scanned project, limit is capped at 100, and offset/limit control pagination. This goes beyond what the annotations and schema alone convey.

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

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

The description is compact and to the point. The one-line summary is front-loaded, followed by an Args block that is easy to scan. Every line adds useful information with no filler 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?

For a read-only listing tool with an output schema and six optional parameters, the description covers all invocation-critical details such as defaults, pagination, and filter formats. It only lacks explicit sibling-tool routing and ordering/sorting behavior, but those are not essential for a correct call.

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%, so the description carries the full burden, and it delivers. Every parameter is explained: severity enum values are listed, category gets examples, file is described as a substring, and offset/limit/path defaults are clarified. This compensates completely for the empty schema descriptions.

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

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

The description opens with a clear verb and resource: 'List findings from the latest scan, optionally filtered.' This is specific and understandable. However, it does not explicitly differentiate itself from siblings like get_finding or scan_project, relying mostly on the tool name and list semantics to do that.

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?

There is no guidance on when to choose this tool over get_finding, scan_project, or generate_report. The mention of 'latest scan' and 'path defaults to the most recently scanned project' offers context but not active routing or exclusions. An agent would have to infer use cases 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?

The description adds substantial behavioral detail beyond the annotations: only plain GET requests are made, localhost is always allowed, other hosts require user ownership confirmation, and the authorized flag must only be set after explicit confirmation. This meaningfully informs the agent about safety and consent requirements, and 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 well-structured and front-loaded with the core purpose, followed by safety/authorization rules and parameter explanations. There is minor redundancy between the 'authorized' explanation in the prose and the Args section, but overall it is efficient and readable.

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, scope, request behavior, ownership authorization, and parameter semantics. With an output schema present and safety annotations already declaring read-only/idempotent/non-destructive behavior, nothing essential is missing for an agent to correctly 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 0%, so the description carries the full burden for parameters. It explains url with concrete examples and explains authorized as requiring explicit user confirmation of ownership or permission, which adds real semantic value beyond the bare 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's function: passively checking a running deployment for a specific list of issues (secrets, exposed files, open databases, CORS, cookies, headers). The verb 'check' plus the explicit resource and scope distinguishes it from sibling tools like scan_project or scan_snippet.

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 strong context for when to use the tool: against a running deployment, using only plain GET requests, and with explicit ownership confirmation for non-localhost hosts. It does not explicitly name alternatives or say when not to use this tool, but the passive-deployment framing makes the intended use 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?

The annotations already communicate read-only, idempotent, open-world, and non-destructive behavior. The description adds useful context beyond those annotations by explaining that dependency lookups happen by default, that offline mode skips network access and registry/vulnerability lookups, and that the scan returns a launch-readiness score.

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 somewhat long because of the comprehensive vulnerability list, but that list earns its place by defining the tool's exact scope. The structure is clear: action, detection scope, then parameter documentation. It is front-loaded and not padded.

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 complex scanner with an output schema, the description sufficiently covers the input parameters, defaults, network behavior, scope, and high-level return value. The annotations cover the read-only and non-destructive profile, so the description is complete enough for an agent to select and invoke the tool correctly.

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

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

The schema has 0% description coverage, so the description carries the full burden for parameter meaning. It explains each parameter clearly: path is an absolute project root defaulting to the client workspace root, check_dependencies enables npm/PyPI/OSV.dev lookups, and offline disables network access. This fully compensates for the bare 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 names a specific action ('Scan'), a specific resource ('a web or mobile app project'), and a concrete outcome ('return a launch-readiness score'). It also enumerates a detailed set of checks, which clearly distinguishes this project-wide scanner from siblings like scan_snippet.

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 intended scope is implied by the first sentence and the coverage list, so an agent can infer it is for project-level security review. However, it never explicitly says when to use this tool versus scan_snippet, list_findings, check_dependencies, or generate_report, and it provides no '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 declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context: filename 'drives language and context detection', and runtime 'auto' guesses from filename/directives. 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 front-loaded with the purpose, then uses a clean Args structure. Every sentence earns its place, and the filename examples are compact yet illustrative.

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 snippet-checking tool with an output schema and read-only annotations, the description covers invocation context fully: what input to provide, how filename affects behavior, and how runtime is determined. Nothing essential is missing for an agent to call 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 0%, so the description fully compensates. It explains code, gives filename semantics with realistic examples, and clarifies runtime values ('client' = shipped to browsers/apps; 'auto' guesses). The only minor gap is not explicitly defining 'server', but it is inferable from the enum and the contrast with 'client'.

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 opens with a specific verb and resource: 'Check a piece of code before writing it to disk'. It also clarifies scope with '(no project needed)' and lists concrete use cases (auth, payment, database, file/URL handling, AI-calling code), which distinguishes it from the sibling scan_project.

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 positive guidance on when to use the tool ('Use it for auth, payment, database, file/URL handling and AI-calling code') and states it needs no project. It does not explicitly name scan_project as the alternative or provide an exclusion condition, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description doesn't need to restate safety. It adds that a fresh re-scan is performed and results are reported as a delta, but it doesn't discuss side effects, cost, or prerequisites; the annotations carry the main behavioral burden.

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 plus a single parameter note, with the main purpose front-loaded and no filler. Every sentence adds useful 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?

For a one-optional-parameter tool with rich safety annotations and an output schema, the description is complete. It covers when to run it, what it reports, and the parameter's default, leaving no obvious gap in the call contract.

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 no schema descriptions on the path parameter, the description fully compensates by defining path as 'Project root' and documenting its default behavior ('defaults to the most recently scanned project'). This is exactly the semantic information an agent needs and goes well beyond the schema's default null.

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 names a specific verb and resource: 'Re-scan the project after edits' and specifies the report contents ('what was fixed, what remains and the score change'). This makes the tool's purpose concrete and differentiates it from initial scans like scan_project and from passive listing tools like list_findings.

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 an explicit trigger: use after edits to verify that fixes took effect. It doesn't name sibling tools as alternatives or exclusions, but the 'after edits' context is clear enough that an agent won't confuse this with initial scanning or finding-listing tools.

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