Hex.pm MCP

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing: not the criteria used to select alternatives, whether results are ranked, how many are returned, or whether an unknown package yields an error. Only 'read-only-ish list' is inferable from the verb.

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?

One short, front-loaded sentence with no filler. However, its brevity comes at the cost of substance rather than being tight-but-complete, so it falls short of a 5.

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

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

With no annotations and no output schema, the description must explain what an 'alternative' result contains and how it is chosen. It omits both, leaving the tool's core semantics undefined for a caller who must decide between it and 23 siblings.

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% and the single parameter ('name', hex.pm package name) is fully documented in the schema. The description adds no format, case-sensitivity, or qualification details, so the baseline 3 applies.

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

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

States a verb ('Find') and resource ('alternative packages'), which is more than a tautology, but never says what makes a package 'alternative' (same category, similar features, comparable downloads) or that the input names the package being substituted. An agent cannot distinguish it cleanly from siblings like 'compare' or 'search'.

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 when-to-use guidance at all. It does not say whether to call this when a package is deprecated, unmaintained, or being replaced, nor does it point to any sibling (e.g. 'compare') for a different need.

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 disclosure burden, and it says almost nothing: it never clarifies whether this is read-only, whether it contacts the registry/network, what 'risks' means (vulnerabilities, outdated deps, licenses), or what happens on failure. For a tool with zero annotation coverage and no output schema, this is thin.

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 six-word sentence with zero padding and the key scope front-loaded. It is efficient, though the brevity shades toward under-specification given the crowded sibling set.

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?

Parameters are fully covered by the schema and no output schema exists, so the description needn't explain returns. What it still leaves unresolved is the disambiguation from 'audit_mix_deps'/'dependencies' and the meaning of 'risks', which an agent needs in order to choose correctly.

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

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

Schema description coverage is 100%, so both parameters ('name' and 'version' with its latest-default behavior) are already documented in the schema. The description adds no extra meaning beyond it, which is the expected baseline when the schema does the work.

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

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

States a specific verb and resource ('Audit package dependencies') plus an outcome ('for risks'), which is clearer than a bare name restatement. However, it does nothing to separate itself from the closely overlapping siblings 'audit_mix_deps' and 'dependencies', so an agent cannot tell which of the near-identical audit tools to pick.

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 when-to-use guidance, no conditions, and no mention of alternatives. With sibling tools named 'audit_mix_deps' and 'dependencies' sitting right next to it, the absence of any routing hint is a real gap.

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 behavioral burden. It does not disclose what 'risks' means, whether the tool is read-only, whether it requires network access, or what the output looks like.

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 with no wasted words. It is concise, though extremely terse, which slightly limits its structural 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?

With no annotations, no output schema, and only a minimal description, the definition is incomplete for an audit tool. It does not explain what the audit returns or help the agent interpret results, leaving significant 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 100%, and the single parameter 'deps' is already documented with an example in the schema. The description adds no additional parameter meaning, so the 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 states a specific verb and resource: 'Audit mix.exs dependencies for risks.' This is clear enough to identify the operation. However, it does not distinguish this tool from siblings such as 'audit', 'dependencies', or 'upgrade_check', so it falls short of a 5.

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

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

There is no guidance on when to use this tool versus alternatives like dependencies, dep_tree, or upgrade_check. The description only restates the tool's purpose without context, exclusions, or routing information.

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 are empty, so the description carries the full burden, yet it says nothing about whether this is a read-only operation, what dimensions are compared, error behavior for invalid/unknown package names, or rate limits. A single sentence leaves the behavioral profile essentially undocumented.

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 with zero filler, which is the right shape for a simple tool. It is arguably under-specified rather than over-verbose, so it lands just shy of 5.

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

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

For a one-parameter tool with full schema coverage and no output schema, a terse description is mostly sufficient, but it omits what the comparison actually returns or on which dimensions, which an agent would reasonably want to know.

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% and the sole parameter is documented as a comma-separated list of 2-5 package names, so the description only echoes the schema. Per the high-coverage baseline, 3 is appropriate with no added syntax or format detail.

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 (compare) and resource (packages) with an explicit scope constraint (2-5). It doesn't name or exclude any of the many sibling tools (info, versions, health, dependencies), so an agent must infer why it would pick compare over those, keeping it below 5.

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

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

No when-to-use context, no prerequisites, and no mention of alternatives among the ~23 siblings such as info or versions. The only guidance is the cardinality limit, which is really a parameter constraint.

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 behavioral burden. It implies a read-only lookup but does not state whether results include transitive, dev, or optional dependencies, nor does it mention pagination, rate limits, or authentication needs.

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 with no wasted words. It is appropriately sized for a simple lookup 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?

The tool is simple, but with no output schema the description could do more to explain the return shape or dependency semantics. It also leaves ambiguity with the sibling 'dep_tree', making the definition only minimally complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters ('name' and 'version'). The description adds no additional parameter semantics beyond what the schema provides, making the baseline score of 3 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 gives a specific verb and resource ('Get dependencies for a package version'), so the core action is clear. However, it does not distinguish this from the sibling tool 'dep_tree', which likely returns overlapping dependency information.

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 explicit guidance on when to use this tool versus alternatives such as 'dep_tree', 'info', or 'versions'. Usage is only implied by the tool name and description.

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 carry the full behavioral burden. It does not disclose whether the operation is read-only, whether it requires authentication or rate limits, or how the tree traversal behaves beyond the schema's max_depth parameter.

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 with no wasted words. It immediately conveys the tool's action and resource, and 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 simple 3-parameter schema with full description coverage and no output schema, the description covers the core purpose. However, the absence of annotations and any usage guidance leaves gaps regarding when to select this tool over siblings and what behavior to expect.

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 parameters are fully documented in the schema. The description adds no additional syntactic or semantic detail beyond what the schema already provides, making a baseline score of 3 appropriate.

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

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

The description states a specific verb and resource: 'Build a package dependency tree.' An agent can infer this recursively compiles dependency information, which is distinct from sibling tools like 'dependencies'. However, it does not explicitly differentiate itself from all alternatives.

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 use this tool versus alternatives such as 'dependencies', 'audit', or 'compare'. The description only states what it does, leaving the agent to infer context from the name and schema.

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 behavioral disclosure burden. 'Get' implies a read operation, but there is no information about permissions, rate limits, data source, or return behavior, and no output schema exists to supplement it.

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 with no wasted words. It is concise but arguably too terse given the tool's context among many siblings.

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

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

With no output schema and no annotations, the description should do more to explain return format, source, and routing versus alternatives. For a documentation lookup tool with many sibling options, one sentence 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 100%, so the schema already documents all three parameters with examples. The description adds no additional semantic detail beyond restating that documentation is fetched for a module or function.

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 clear verb and resource: get documentation for a module or function. It does not distinguish this tool from siblings such as docs or search_docs, and the 'or function' wording is not supported by a function parameter in the schema.

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 use this tool versus alternatives like docs, readme, info, or search_docs. The usage context is only implied by the tool name and description.

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 at all, the description carries the full burden of behavioral disclosure and does not meet it. It says nothing about whether the result is paginated, how large a listing may be, whether a non-existent package errors, or what the response shape is.

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 short phrase with no waste, but it is concise through under-specification rather than disciplined front-loading. There is no structure to speak of — just a noun phrase.

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

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

With no annotations and no output schema, the description is the only source of behavioral and usage context, and it is inadequate for a tool sitting among ~23 doc-related siblings. An agent cannot reliably tell when this tool applies or what it returns.

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

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

Schema description coverage is 100%, so both parameters ('name' and 'version') are already fully documented in the schema, including the 'defaults to latest' behavior. The description adds nothing beyond that, which merits the baseline 3.

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

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

Names a verb ('Browse') and a resource ('package documentation module listing'), so the general intent is graspable, but 'documentation module listing' is ambiguous — it is unclear whether this returns a list of modules, a module's contents, or a rendered doc page. It does not distinguish itself from close siblings like doc_item, search_docs, or readme.

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 offers no guidance on when to use this tool versus the many adjacent doc-related siblings (doc_item, search_docs, readme). No prerequisites, no exclusions, no indication of what makes this the right choice.

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 responsibility for behavioral disclosure. It implies a read-only operation via 'Get' but says nothing about side effects, authentication requirements, rate limits, or the structure of returned data, which is a significant gap for a tool with no annotation coverage.

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 with no wasted words. It is appropriately sized for a simple tool and every word earns its place.

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

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

Given the tool's simplicity and full parameter documentation in the schema, the description is adequate but leaves gaps. With no output schema and no annotations, it could clarify what the download statistics represent (e.g., total counts, time series, per-version breakdown), but it provides only a high-level summary.

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% since the single 'name' parameter is fully documented in the schema as 'Package name on hex.pm'. The description adds no additional meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Get') and resource ('package download statistics'), making the tool's function immediately clear. It does not explicitly differentiate itself from siblings like 'info' or 'health', but the resource is distinctive enough for an agent to distinguish it.

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 'info', 'health', or 'versions'. There is no mention of context, prerequisites, or exclusions, leaving the agent to infer usage entirely.

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 are empty, so the description carries the full burden. 'Get' implies a read, but nothing is said about what happens for packages with no declared features, whether a missing version errors, or what the response contains. No output schema exists to cover the return shape either.

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 short sentence with the resource front-loaded and no waste. Under-specification is the issue, not verbosity.

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 read tool with a fully documented schema, the description is minimally adequate, but it leaves the ambiguous term 'features' undefined and says nothing about error or empty-result behavior in the absence of annotations and an output schema.

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

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

Schema description coverage is 100%, and the schema already documents both 'name' and 'version' (including the default-to-latest behavior). The description adds no parameter detail beyond 'for a package release', so baseline 3 applies.

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

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

States a specific verb+resource: retrieving optional features for a package release. It is clear enough to act on, but it does not distinguish itself from siblings like 'info', 'release', or 'versions', which could plausibly also describe release metadata.

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 call this versus 'info' or 'release', and no prerequisites (e.g. that the package/version must exist). The agent must infer usage 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 are provided, so the description carries the full disclosure burden. It does not state that this is a read-only query, whether it makes network calls, whether hit rate limits apply, or what a 'comprehensive' check includes — only the read-only nature is weakly implied by 'health check'.

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 with zero filler. Nothing is wasted and the core action appears immediately.

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

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

With no annotations and no output schema, the description should say what the health check reports and roughly what it returns. 'Comprehensive' is the only hint, leaving scope and return content undefined for a tool whose value depends on what it surfaces.

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 single parameter is fully described ('Package name on hex.pm'), so the description need not carry parameter burden. It adds nothing beyond the schema, which is acceptable at this coverage level — baseline 3.

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

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

States a verb and resource (run a package health check), so the general action is clear. However, 'health' is left undefined — nothing says whether it covers dependencies, versions, security, or documentation — so the agent cannot tell how it differs from siblings like audit, upgrade_check, or info.

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 when-to-use guidance and no mention of alternatives. With close siblings such as audit and audit_mix_deps in the list, the agent gets no signal for choosing this tool over those; usage must be inferred 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 are provided, so the description carries the full behavioral burden. It implies a read-only lookup but never states that, nor does it disclose response shape, caching, rate limits, or error behavior for nonexistent packages. For a tool with zero annotation coverage this is a notable gap.

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 efficient sentence with no filler. It is front-loaded and wastes nothing, though brevity here borders on under-specification rather than tight scoping.

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

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

With no annotations, no output schema, and many domain-specific siblings, the description does not provide enough context for an agent to invoke confidently or predict the return. It should at least enumerate what 'detailed information' includes and how it differs from neighboring tools.

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% and the single 'name' parameter is documented in the schema as 'Package name on hex.pm'. The description adds no parameter detail beyond that, so the baseline 3 for fully-covered schemas applies.

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

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

States a clear verb+resource: fetches detailed information for a package. An agent can understand the operation, but the description never distinguishes this tool from siblings like versions, docs, owners, or readme, which all surface package-related data. Without that differentiation the agent cannot tell what 'detailed' uniquely covers.

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 when-to-use guidance at all. With siblings such as versions, docs, release, owners, and health available, the description gives no signal about when 'info' is the right choice versus a more specific tool.

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

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

Annotations are empty, so the description carries the full burden. 'Get' implies a read operation, but nothing is said about whether results are paginated, whether authentication is required, or what happens for a package with no listed maintainers.

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 short sentence with zero filler and the resource front-loaded. It is appropriately sized for a one-parameter lookup, though it is arguably under-specified rather than optimally 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?

For a simple one-param read with no output schema, the definition is minimally viable but leaves the return shape (a list of names? roles? emails?) unstated, which an agent would need in order to use the result 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?

There is a single parameter and the schema documents it fully ('Package name on hex.pm'), so the schema does the heavy lifting. The description adds no syntax, format, or constraint detail beyond that 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?

States a specific verb ('Get') and resource ('package owners and maintainers'), which disambiguates a terse tool name that could otherwise read as ownership management. It does not explicitly contrast with siblings like info or dependencies, but the resource is concrete enough for selection.

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 no indication of when to reach for this tool versus siblings such as info, versions, or dependencies, and states no preconditions. Usage must be inferred entirely from the resource noun.

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 are empty, so the description carries the full burden. It doesn't say the return format (raw markdown vs rendered), whether a missing README errors or returns empty, or whether it is a safe read. For a no-annotation tool this is thin.

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 with zero waste. It is underspecified rather than bloated, so conciseness itself is fine.

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 two-parameter read tool with no output schema and no annotations, the description covers the core action but omits return format and error behavior. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so both parameters (name, version) are already documented in the schema. The description adds no extra meaning, which is acceptable baseline behavior 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?

States a specific verb+resource: fetch a package's README content. An agent knows what it returns, but the description makes no attempt to distinguish it from nearby siblings like docs or doc_item, which could also surface package documentation.

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 when-to-use guidance at all. Nothing tells an agent why to pick readme over docs, doc_item, or search_docs, which is a real ambiguity in this sibling set.

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. 'Get' implies a read-only operation, but nothing is said about what 'detailed' includes, error behavior for nonexistent versions, or any rate limits, so the agent gets no behavioral context beyond the verb.

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 short sentence with no padding, and the purpose is front-loaded. It is efficient, though its brevity is partly a symptom of missing detail rather than disciplined editing.

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 read tool with a fully documented schema and no output schema, the description is minimally viable. It omits what the returned 'detailed' information covers and how it differs from sibling retrieval tools, leaving a modest gap.

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

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

Schema description coverage is 100%, so both name and version are already documented with format hints (hex.pm package name, example version '1.8.5'). The description adds no extra meaning beyond what the schema provides, making the baseline 3 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?

States a clear verb (Get) and resource (package release information), scoped by the required name and version parameters. It does not distinguish itself from close siblings like versions, info, or docs, so an agent must guess which one to call for version-specific detail.

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 indication of when to use this instead of versions, info, or docs, and no prerequisites stated. The only implicit cue is that it requires an exact version, which an agent could infer from the schema but not from the description.

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, and it discloses almost nothing: no mention of result format, pagination limits, rate limits, or whether the search is exact vs fuzzy. The only behavioral hint is the schema's page/sort params, which the description itself does not explain.

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 short, front-loaded sentence with zero waste. It is efficient, though arguably underspecified rather than truly concise about behavior.

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 three-parameter tool with full schema coverage and no output schema, the essentials are present via the schema. Still missing is any statement of result scope, pagination defaults, or how it relates to the other search-ish siblings, which matters given a crowded sibling list.

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

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

Schema description coverage is 100%, with query, page, and sort all documented inline (including the sort enum values). The description adds no extra meaning beyond that baseline, which is adequate but not enhancing.

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

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

States a specific verb and resource ('Search hex.pm packages'), so an agent knows this queries the package registry. However, it offers no differentiation from siblings like search_docs or toolbox_search, which could also be described as searches, leaving overlap to be inferred.

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 when-to-use or when-not-to-use guidance. The description does not say how this differs from search_docs (documentation search) or toolbox_search, so the agent must guess which search surface to pick.

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 present, the description carries the full burden of behavioral disclosure. It states the tool searches documentation but does not describe read-only behavior, authentication needs, rate limits, result format, or pagination.

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 with no wasted words. It is appropriately sized for a short search tool, even though it is under-specified elsewhere.

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 annotations and no output schema, the description should provide more context about usage, return values, or relationship to sibling tools. It leaves the agent to infer when and how to use this search versus docs or doc_item.

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 input schema already documents name, query, and version. The description adds no additional parameter semantics beyond 'package documentation,' making the baseline of 3 appropriate.

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

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

The description states a specific verb and resource: 'Search within package documentation.' This clearly identifies the operation, though it does not name or distinguish itself from siblings such as docs, doc_item, or search.

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 like docs, doc_item, or the general search tool. It implies a context for searching documentation but offers no explicit conditions 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?

Annotations are empty, so the description carries full burden. 'List' implies a read-only operation, but there is no disclosure of pagination, rate limits, permissions, or return shape. Only minimal safety context by implication.

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?

One short, front-loaded sentence with zero filler. However, the extreme brevity leaves the tool under-explained for its sibling context, though that is a completeness issue rather than a structure issue.

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, and the schema fully documents all three parameters. Still, with no annotations and no output schema, the description could clarify return behavior, default paging, and how it differs from sibling listing tools. Adequate but thin.

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 defines sort, group, and category. The description adds no parameter-level meaning beyond the schema, which is the expected baseline 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?

States a specific verb 'List' and resource 'projects' scoped to a Toolbox category, so the basic action is unambiguous. It does not differentiate from sibling tools like toolbox_search or toolbox_trending, which also return project lists, so it falls short of a 5.

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

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

No when-to-use guidance, no stated alternatives, and no conditions that select this tool over siblings. The required 'group' and 'category' parameters imply a hierarchical browse, but the description never says so.

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, but it discloses nothing beyond the bare purpose: no return shape, no pagination, no auth or permission requirements, and no behavior for an unknown group slug. For a read-only listing this is a minor gap, but it is a gap.

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 short sentence with no filler, and the core action is front-loaded. It is appropriately sized for such a simple tool, though it could have spent one clause on sibling differentiation.

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 annotations mean the description must supply context, yet it does not say what the categories are, how they relate to the sibling tools, or what happens on an invalid group. For a tool sitting in a very crowded namespace, it is under-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% and the single 'group' parameter is documented with an example slug ('web', 'ai'), so the schema does the heavy lifting. The description adds no meaning beyond that 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 states a clear verb and resource ('List categories in a Toolbox group'), so the basic purpose is legible. However, the sibling set contains near-identical names (toolbox_group, toolbox_groups, toolbox_category), and nothing here distinguishes them, leaving real ambiguity about what 'categories in a group' means versus those alternatives.

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 use this tool versus toolbox_groups, toolbox_category, or toolbox_search. No prerequisites (e.g. whether the group must already exist) are stated either.

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 behavioral burden. 'Browse' weakly implies a read-only operation, but no auth requirements, rate limits, pagination, return format, or side effects are disclosed. The description adds almost nothing 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 a single short noun phrase with no wasted words, but it is also under-specified for a tool with many similarly named siblings. It is concise without being structured enough to aid 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?

With no output schema, no annotations, and zero parameters, the description is the main source of context, yet it does not explain what groups are or when to choose this tool over the many sibling browse/search tools. An agent could easily select the wrong taxonomy-related 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 takes zero parameters, so the baseline is 4. The schema is empty and parameter description coverage is irrelevant here; the description does not need to document any inputs.

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 broad verb-resource: 'Browse the Elixir Toolbox taxonomy.' However, it does not specify what a 'group' is, what browsing returns, or how this differs from siblings like toolbox_group, toolbox_category, and toolbox_search. The purpose is implied but not precisely distinguished.

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 when-to-use guidance, no alternatives named, and no exclusions. The agent must guess whether to use this versus toolbox_group, toolbox_category, toolbox_search, or toolbox_trending based only on the name.

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 implies a read-only lookup but never states that explicitly, nor covers result format, pagination, or limits. For a search tool with zero structured coverage, this is thin.

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 short sentence with no wasted words and the core action front-loaded. It is efficient, though arguably terse to the point of under-specification.

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 search with no output schema, the basics are covered. But the absence of any distinction from the sibling 'search' or mention of what results look like leaves real gaps for correct tool selection.

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?

There is a single 'query' parameter with 100% schema description coverage, so the schema already documents it. The description adds no syntax, matching behavior, or format guidance beyond what the schema provides, making the baseline 3 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 names a specific verb ('Search') and resource ('packages through Elixir Toolbox'), so the action is unambiguous. However, it offers no differentiation from the sibling tool 'search', leaving the agent to guess which one to pick.

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 statement of when to use this tool versus the near-identical sibling 'search', nor any prerequisites or context. The agent must infer usage entirely from the name.

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 behavioral burden. It does not define what 'trending' means (time window, ranking basis), whether results are paginated, or what the response shape looks like, which matters for a discovery 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?

A single front-loaded sentence with zero filler, which is appropriately terse for a simple list tool. It is concise to the point of under-specification, but no sentence is wasted.

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-parameter list tool with full schema coverage this is minimally viable, but the absence of annotations and any output schema means the undefined notion of 'trending' and the return format are left unexplained.

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 single limit parameter is already documented as 'Maximum number of projects to return'. The description adds no additional semantics (default value, max bound) beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('List') and resource ('trending Elixir packages'), so the agent knows exactly what it returns. However, it offers no differentiation from nearby siblings such as toolbox_search, toolbox_category, or search, which could also surface packages.

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 toolbox_search or toolbox_category. The description gives no preconditions, no alternatives, and no exclusions, leaving the agent to infer usage 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?

With no annotations and no output schema, the description carries the full behavioral burden, yet it discloses almost nothing. It doesn't say whether the check hits the network, consults a lockfile, requires a mix.lock, how it handles private/hex deps, or what the result looks like.

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 short sentence, front-loaded with the verb and scope, with no wasted words. It is terse to the point of being under-specified, but the structure itself is clean.

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

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

For a tool with no annotations and no output schema, the description should explain what a 'check' yields (outdated versions, available upgrades, warnings). Nothing about the return shape or prerequisites is given, leaving an agent unable to predict the outcome.

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% and the single 'deps' parameter is documented with a concrete example of the expected Mix deps text format. The description adds nothing beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb ('Check') and resource ('mix.exs dependencies for upgrades'), so an agent knows it inspects dependency versions for available upgrades. It does not, however, distinguish itself from sibling tools like audit_mix_deps or dependencies, which sound closely 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?

There is no statement of when to use this tool versus the many sibling alternatives such as audit_mix_deps, dependencies, dep_tree, or versions. The agent must infer the intended context 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 are provided, so the description carries full behavioral burden. It implies a read-only listing but omits whether the output is paginated, sorted, or requires authentication, and gives no 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?

Extremely concise and front-loaded with no wasted words, but its brevity borders on under-specification rather than elegant 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 simple one-parameter listing tool with no output schema or annotations, the description is minimally adequate: an agent can invoke it correctly. It could be improved with output format or sibling distinction, but nothing critical is missing for basic 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 coverage is 100%, and the description adds no parameter meaning beyond what the schema already provides ('Package name on hex.pm'). Baseline 3 applies 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?

States a specific verb and resource ('List ... package versions'), making the action clear. However, it does not differentiate from siblings like 'info' or 'release', which may also return version-related data.

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 such as 'info' or 'release'. The agent must infer that it is for retrieving the full version history of a package.

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