Commit — Supply Chain Risk Scoring

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

With no annotations, the description carries the full burden of behavioral disclosure. It explains the risk flag logic (CRITICAL, HIGH, WARN), the output sorting by commitment score, and the Go-specific maintainers-column nuance. This adds substantial context beyond the schema, although it does not cover aspects like rate limits or error behavior.

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

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

The description is well-structured with a clear lead sentence, a bulleted list of risk flags, and a use-case paragraph. It is somewhat long, but every section is informative and necessary for a tool covering four ecosystems with subtle behavioral rules.

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 two-parameter tool with no output schema, the description is remarkably complete. It covers the output format, risk scoring criteria, ecosystem-specific behavior, and actionable examples, leaving users with enough understanding to invoke the tool correctly for their dependency file.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful elaboration. It reiterates the Go full-module-path requirement, clarifies the auto-detection behavior, and provides concrete examples for all ecosystems. This goes beyond the schema by tying parameters to real-world usage patterns.

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 the specific verb phrase 'Batch-score multiple npm, PyPI, Cargo, or Go packages for supply chain risk,' immediately stating the tool's function and scope. This clearly distinguishes it from sibling single-package lookup tools and audit_github_repo, which focus on a single package or repository.

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

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

The description provides clear context for when to use the tool: 'Perfect for auditing a full package.json, requirements.txt, Cargo.toml, or go.mod' and includes example use cases (score all deps, compare packages, identify abandonware). It does not explicitly state when not to use it or name alternative tools, but the batch-oriented framing implies the distinction.

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, so description carries full burden. It details traversal behavior (depth semantics), defines risk flag thresholds, and notes performance tradeoffs ('slower'). This is rich behavioral disclosure beyond a simple 'gets dependencies'.

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?

Though long, the description is well-structured with headers, bullets, and examples. Every section adds value: overview, risk flags, depth explanation, examples, and use-case triggers. No filler or tautology.

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, and the description does not explicitly describe the response format. While it thoroughly explains functionality and risk flags, an agent might not know the exact structure of the returned dependency tree. Minor gap, but overall comprehensive.

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?

Despite 100% schema coverage, the description adds crucial semantics: explains depth=2 only traverses CRITICAL/HIGH direct deps, and provides multiple working examples with different package names. This goes far beyond the schema's 'minimum' and 'maximum'.

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 'Map the full dependency tree of an npm package and identify CRITICAL supply chain risks at every level.' Clearly specifies verb (map/identify), resource (npm dependency tree), and scope (full tree with risk flags), distinguishing it from flat-list audit and lookup tools.

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

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

Explicitly contrasts with 'auditing a flat list of packages' and provides a 'Use this when' list with natural language queries. This gives clear guidance on when to prefer this tool over siblings.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explains that it fetches package.json/requirements.txt, runs behavior commitment scoring, and returns a risk table with specific flag criteria (CRITICAL, HIGH, WARN). It does not mention network/rate limits or authentication, but given it's a read-only audit, the disclosure is solid and adds context beyond the 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 front-loaded with the core purpose and uses well-separated sections (risk flags, examples, usage trigger). Every sentence adds value; the length is justified by the lack of annotations and output schema. No filler 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?

Despite having no output schema and no annotations, the description covers the process, inputs, and the meaning of risk levels, giving a comprehensive picture. It stops short of describing the exact response structure (e.g., JSON shape) but provides enough for an agent to know what to expect. A perfect score would require more detail on output format or edge cases.

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's description for 'repo' already covers accepted formats ('owner/repo', GitHub URL) and provides examples. The tool description repeats some examples but adds no new parameter-level meaning. Since schema coverage is 100%, the baseline of 3 is appropriate—the description does not need to compensate.

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

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

The description clearly states the tool's function: 'Audit the supply chain risk of a GitHub repository's dependencies.' It specifies the verb (audit), resource (GitHub repository's dependencies), and method (fetches package.json/requirements.txt, runs behavioral commitment scoring). It also provides examples and distinguishes from siblings by being GitHub-specific.

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

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

The description explicitly says 'Use this when someone asks "is my project at risk?" or "audit this repo's dependencies"' and highlights it as 'the fastest way to audit a project.' It does not explicitly name alternatives or when not to use it, but the GitHub-specific focus and examples provide clear context. Since it lacks explicit exclusions or alternative references, it slightly misses 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?

No annotations are provided, so the description carries the full burden. It discloses rate limit changes ('lifts the rate limit to 200 audits/day'), enables monitoring, and states constraints: 'One key per email. 3 keys per IP per day (anti-abuse).' It also explains the returned key and usage in an MCP client configuration, providing strong behavioral transparency.

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

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

The description is moderately sized but well-structured: it leads with the core purpose, explains the benefit, gives an example, and lists constraints. All sentences carry useful information, though the second sentence partially restates the first. It earns a 4 for effective structure with minor 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?

Given it's a simple one-parameter tool with no output schema, the description covers the purpose, usage trigger, benefits, and post-process configuration. It doesn't explicitly detail the response format, but the example and statement 'returned directly in the chat' are sufficient. The tool is adequately contextualized within the sibling set.

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

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

The schema already covers the email parameter with a detailed description and validation. The tool description adds extra context about why the email is needed and the rate limit benefits, enriching the parameter semantics. Since schema coverage is 100%, the baseline is 3, and the added context justifies a 4.

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

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

The description begins with 'Create a free Commit API key instantly — no browser required,' which clearly states a specific action (create) and resource (Commit API key). This distinguishes it from the sibling audit/lookup tools that retrieve data rather than generate credentials.

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

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

It provides explicit usage context: 'When you've hit the daily free query limit (or just want faster access), call this tool with your email...' This tells the agent when to invoke the tool, though it does not explicitly state alternatives or when not to use it. Sibling tools are all lookup/audit operations, so the use case is clear.

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

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

With no annotations, the description carries the full burden. It discloses the data source (Brønnøysund Register Centre), the nature of the data ('real commitment signals', 'verified, unfakeable'), and what is returned. It doesn't mention limitations or output format details, but overall provides meaningful 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 two sentences, front-loaded with the core action and output, followed by data source and quality attributes. 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?

Given the tool's simplicity (one parameter, no output schema), the description covers the essential aspects: what it searches, what it returns, and where the data comes from. Missing are specifics like response format or edge cases, but these are not critical for such a straightforward lookup tool.

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

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

Schema description coverage is 100%, so the schema already documents the only parameter ('query'). The tool description adds context about Norwegian business but no additional syntax, formatting, or examples beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb ('Search'), the resource ('Norwegian business'), and the specific output ('commitment profile') with concrete signals (longevity, financial health, employee count, commitment score). It differentiates from sibling lookup tools by specifying Norwegian business data and government sources.

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

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

The description provides clear context for when to use the tool: when you need a commitment profile for a Norwegian business. It doesn't explicitly mention alternatives (like lookup_business_by_org) or exclusions, so it falls slightly 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?

With no annotations provided, the description carries the transparency burden. It discloses the data source (Brønnøysund Register Centre) and the nature of returned data (temporal, financial, and operational commitment signals). While it doesn't explicitly state side effects or limitations, a lookup operation is inherently read-only, and the description offers useful context.

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

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

The description is a single sentence that is front-loaded with the action and key parameters, and every phrase is informative. No unnecessary repetition or filler.

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

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

For a simple one-parameter lookup tool with no output schema, the description covers what it does, what it returns, and the data source. It could mention error cases or when not to use it, but overall it is adequately complete for the tool's simplicity.

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

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

The input schema already fully documents the orgNumber parameter including format and example. The description reiterates the 9-digit format and adds Norwegian business context, but doesn't provide new semantic details beyond the schema, so it meets the baseline.

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

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

The description uses a specific verb ('look up') and resource ('Norwegian business by organization number (9 digits)') and adds the distinct output ('commitment profile') from the Brønnøysund Register Centre. This clearly distinguishes it from siblings like lookup_business and query_commitment.

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

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

The description clearly states the use case: looking up a specific Norwegian business using its org number. It implicitly signals that this is for Norwegian entities only, unlike broader tools like lookup_business, but it doesn't explicitly mention alternatives 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 carries the transparency burden. It discloses specific output details (e.g., 'download volume (estimated weekly from 90-day totals)') and the type of signals returned. It doesn't mention failure modes, authentication, or side effects, but for a read-only lookup tool, the provided behavioral details are robust and exceed minimal expectations.

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 and well-structured: a clear opening statement, a list of return signals, a motivational risk paragraph, and explicit use cases with example values. Every sentence adds value, and the front-loading ensures the agent immediately knows the tool's 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 simple one-parameter tool with no output schema or annotations, the description provides sufficient context: what it does, what it returns (detailed signal list), and when to use it. It even provides example crate names to guide parameter construction. 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 input schema already provides full parameter documentation with examples and case-insensitivity note (100% coverage). The description reinforces the crate context but doesn't add new parameter-specific meaning beyond what the schema states. Per rubric, baseline is 3 when schema coverage is high.

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

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

The description starts with a specific verb and resource: 'Get a behavioral commitment profile for any Rust crate on crates.io.' It clearly distinguishes this from sibling lookup tools for npm, PyPI, and Go modules by focusing on crates.io and Rust-specific signals. The scope is unambiguous.

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

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

The description provides explicit use cases: 'vetting Rust dependencies before adding to Cargo.toml, identifying abandonware, supply chain risk assessment.' This gives clear context for when to use the tool, though it doesn't explicitly name alternatives or say when not to use it. Since the tool is language-specific, the use cases effectively differentiate it from sibling lookups.

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. It discloses that the tool returns behavioral signals (project age, commit frequency, contributor community, release cadence, social proof) and restricts to public repositories, but it does not mention edge cases like invalid/private repos or whether data is cached. This meets the baseline but lacks deeper behavioral disclosure.

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

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

The description is compact and front-loaded, using three sentences to cover purpose, use cases, and examples. Each sentence adds value; the 'harder to fake' clause provides useful conceptual context without fluff.

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

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

For a single-parameter lookup with no output schema, the description gives sufficient context: what it does, what it returns, use cases, and example inputs. It omits error-handling or rate-limit details, but for the core decision and invocation scenario it is complete enough.

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

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

The input schema already describes the 'repo' parameter with format and examples, and schema coverage is 100%. The description repeats example formats, reinforcing syntax but adding little new parameter-level meaning. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description uses the specific verb phrase 'Get a behavioral commitment profile' and clearly identifies the resource as 'any public GitHub repository', making the tool's purpose unambiguous. It distinguishes from sibling package lookups and from audit_github_repo by framing the output as a commitment profile rather than an 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 'Useful for' list provides concrete scenarios (vetting open-source dependencies, evaluating AI tools/frameworks, assessing vendor reliability, due diligence) that tell an agent when to choose this tool. It does not explicitly name alternatives or exclude cases, but the context is clear enough to guide selection.

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

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

The description explains that Go has no centralized download counter, so the profile is GitHub-primary and stars are used as the popularity proxy. This discloses behavioral characteristics about the data source and interpretation beyond what the schema/annotations provide. No annotations exist, so this context is essential for understanding the returned signals.

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 details signals, ecosystem context, use cases, and examples. It is well-structured and each paragraph serves a clear function, though the example list is somewhat redundant with the schema. Overall it's appropriately sized for the tool's complexity.

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

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

The description covers the tool's purpose, the exact signals returned, the ecosystem rationale, and typical use cases. With only one parameter and no output schema, the description sufficiently describes the output by enumerating the signals (module age, version count, etc.). This is complete for a lookup 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 schema already provides 100% coverage of the 'module' parameter with details about full path, host, examples, and case-sensitivity. The description repeats the examples but adds context about the Go ecosystem's reliance on the module path. However, it doesn't add significant new semantic meaning 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 opens with 'Get a behavioral commitment profile for any Go module on proxy.golang.org', which is a specific verb+resource+scope. It also lists the signals returned and distinguishes itself from sibling ecosystem lookup tools by focusing on Go modules. This clearly states the tool's function.

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

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

The description explicitly states 'Useful for: vetting Go dependencies before adding to go.mod, identifying abandonware, supply chain risk assessment.' This provides clear usage context for when to invoke the tool. While it doesn't name alternative tools, the context is sufficient to infer appropriate use within the Go ecosystem.

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 fully carries the transparency burden. It explains the tool's non-obvious behavior, such as returning a publisherLifecycle metric and the rationale for behavioral signals, including a security incident example. It does not disclose potential rate limits or data sources, but the description gives a robust picture of what the tool does and why.

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 longer than average but well-organized into distinct sections: main functionality, additional metric, rationale, and use cases. Each section adds value; the Mastra incident example is vivid but slightly extraneous. Overall it is efficiently structured for the complexity.

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 that there is no output schema, the description compensates by enumerating the returned signals (age, downloads, trend, contributors, etc.) and explaining the publisherLifecycle concept. The single parameter is simple, and the use cases are clear. Complete enough for an agent to invoke correctly, though a note on return format would make it fully exhaustive.

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

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

The input schema already provides 100% coverage for the single parameter, including examples and a scoping note. The description repeats the examples and adds broader context about the tool's purpose, but it does not add new parameter-specific details beyond the schema. 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 opens with 'Get a behavioral commitment profile for any npm package,' which is a specific verb+resource statement. It clearly distinguishes from sibling tools like lookup_github_repo and lookup_pypi_package by targeting npm packages and focusing on behavioral signals. The list of returned signals further clarifies the scope.

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

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

The description includes a 'Useful for' section listing concrete scenarios (vetting dependencies, due diligence, identifying abandonware) and provides examples. However, it does not mention alternative tools explicitly or state when not to use this tool, so it falls short of the highest bar.

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 carries the full burden. It does disclose the return content (signals) and implies a read-only lookup, but it does not mention rate limits, authentication, errors, or side effects. The supply-chain anecdote adds context but isn't a behavioral disclosure, so the transparency is adequate but not detailed.

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 purpose, but the second paragraph about the LiteLLM incident is somewhat tangential to tool selection or invocation. It adds context but is not essential and could become stale. The structure is clear, but the length could be reduced without losing core guidance.

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 single-parameter lookup tool, the description covers the essential context: what it does, what data it returns, and when to use it. The absence of an output schema is mitigated by the description listing the returned signals. It doesn't explain auth or pagination, but these are less critical for a straightforward package lookup.

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

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

Schema coverage is 100% and the schema already describes the 'package' parameter with examples and case-insensitivity. The description reinforces this by listing example package names, but adds no new parameter-level semantics beyond what the schema provides. Baseline 3 applies because the schema carries the load.

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, specific verb+resource combination: 'Get a behavioral commitment profile for any PyPI (Python) package.' It lists exactly what signals are returned (age, downloads, release consistency, etc.), and the PyPI scope differentiates it from sibling tools like lookup_npm_package or lookup_go_module.

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

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

The description provides explicit use cases: 'vetting Python dependencies, identifying abandonware, supply chain risk due diligence.' The package name examples further clarify when to use this tool. However, it doesn't explicitly mention when not to use it (e.g., if you need an audit or GitHub-specific analysis), so it lacks exclusion statements.

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?

There are no annotations, so the description carries the full burden. It discloses that the data is 'verified' and returns 'aggregated signals,' which adds meaningful context beyond a simple read operation. However, it does not mention operational details such as whether the data is cached, potential rate limits, or errors on unknown domains. Some context is provided, but not exhaustive.

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

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

The description is three sentences: the first states the action, the second lists the return values, and the third explains its value proposition. Every sentence earns its place without redundancy. It is front-loaded with the core purpose and remains 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?

The tool is simple with one parameter and no output schema. The description sufficiently explains what the tool returns and why it is useful, covering the return values in enough detail. However, because there is no output schema, it could benefit from a brief note on output format or error behavior, which is a minor gap.

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

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

With 100% schema coverage, the input schema already documents the 'domain' parameter thoroughly, including normalization. The description adds no extra meaning about parameters, so the baseline of 3 applies. It neither enhances nor detracts from the schema's clarity.

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: 'Query verified behavioral commitment data for a domain.' It lists specific outputs (unique verified visitors, repeat visit rate, average time spent), which distinguishes it from sibling lookup tools that focus on business, packages, or repositories. The verb and resource are specific, making its purpose unambiguous.

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

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

The description provides clear context for when to use this tool: when you need to prove real human engagement, as it says the data is 'harder to fake than reviews or content.' However, it does not explicitly state exclusions or compare directly to alternatives like 'use this instead of lookup_business.' Thus it has clear context but lacks explicit when-not guidance.

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