Global Executables

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, yet the description adds genuinely non-obvious behavior: no live registry call is made, scope filters providers before signals are aggregated, release age uses a 365-day threshold measured against request time, and unknown/insufficient_evidence signals missing snapshot evidence rather than safety. The last point is a critical interpretation caveat that prevents a false 'safe' conclusion.

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?

Front-loaded with purpose, then constraints, then result-interpretation caveats — a sensible ordering with no filler. The middle sentence is dense and packs several clauses together, but each clause carries distinct information.

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

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

An output schema exists, so return structure need not be described, and the description instead covers what an agent cannot get from schema or annotations: the absence of a live registry call and the meaning of unknown/insufficient_evidence. Nothing needed to call or interpret the tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value beyond the schema: scope narrows providers before signal aggregation, and the 365-day age threshold explains how the name/age interaction is evaluated. The usage-count fallback ('usage counts can still establish activity') clarifies how signals combine when age is stale.

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 (assess) plus the resource (one command name) and enumerates the four dimensions scored (freshness, activity, popularity, collision risk). The word 'one' plus the explicit contrast with the plural sibling assess_executables makes it unambiguous which tool handles a single name.

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 positions the tool in a workflow ('after an existence check'), names the batch alternative (assess_executables for several names), and states a prohibition ('do not use it instead of check_executable'). When-to-use, when-to-batch, and when-not-to-use are all covered.

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?

Goes well past the annotations (which only cover read-only/idempotent/openWorld): it discloses that no live registry call is made, that unknown/insufficient_evidence denotes missing snapshot evidence rather than safety, that a single scope filters all names before aggregation, and that duplicates/order are preserved. These are exactly the behavioral facts an agent needs to interpret results correctly.

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?

Purpose and routing are front-loaded in the first two sentences, and the remaining text is dense with non-redundant behavior. It is slightly run-on and mixes instruction with description ('so retain each result's existence and coverage context'), costing a point.

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 an output schema present, return values need not be described, yet the description still explains how to interpret ambiguous result states and ordering. For a two-parameter batch read tool, nothing an agent needs to call or interpret it is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds genuine meaning beyond the schema for scope ('One scope filters every name before per-name signal aggregation') and for names (release age uses request time, results preserve input order, duplicates retained).

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 (assess) plus the exact signals computed (freshness, activity, popularity, collision risk) and the batch scope (several command names). This distinguishes it immediately from the singular sibling assess_executable and from the check_* family.

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 routes the agent: 'use assess_executable for one' and 'do not use it instead of check_executables'. That is a positive selection rule plus an exclusion, which is the strongest form of usage guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, and the description still adds substantive behavior: no live registry call, never runs or installs software, hits return providers, and misses are only conclusive when coverage_scope is exhaustive. That is exactly the extra context the annotations do not carry.

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?

Front-loaded with purpose, then alternatives, then behavioral caveats, so an agent can stop reading early. It is somewhat dense and repeats the non-exhaustive-scope idea once, but no sentence is 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 two-parameter lookup tool with full schema coverage and an output schema, the description covers routing, case-sensitivity, scope semantics, and the crucial exhaustiveness caveat on negative results. Nothing an agent needs to call it or interpret a miss is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: name is case-sensitive and not normalized, and scope filters providers with AND semantics before the collision decision. It stops short of enumerating valid scope keys, leaving that to 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 first sentence gives a specific verb, resource and scope: check one exact command name for a collision in the indexed snapshot. It explicitly distinguishes itself from check_executables (several) and search_similar_executables (fuzzy discovery), so an agent can route correctly without opening a 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?

It states when to use this tool ('one candidate'), when to use the sibling instead ('several' -> check_executables), and when not to use it at all ('do not use it for fuzzy discovery'). It also warns that a scoped miss is non-exhaustive, which is a prerequisite an agent needs before acting.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavior: no live registry call, never executes software, misses are 'unknown' rather than negative, and supplied scopes are never exhaustive. This is exactly the caveat an agent needs to avoid over-interpreting results.

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?

Front-loaded with purpose, then alternatives, then semantics and caveats. Every clause earns its place, though the second half is dense with em-dash asides and could be tightened slightly.

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 an output schema present and annotations covering safety, the description supplies the remaining essentials: batch semantics, ordering guarantees, alternatives, and the non-exhaustive-coverage caveat. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema does not state per-field: one scope filters every name with AND semantics, each name is evaluated independently, and duplicates are preserved in input order. That explains how the two parameters interact in a batch call.

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

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

States a specific verb (check), resource (several exact command names), and scope (collisions in one indexed snapshot), and immediately distinguishes itself from the singular check_executable. An agent can identify the batch variant without opening 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?

Explicitly routes usage: 'Use this for multiple candidates; use check_executable for one, and do not use it to rank similar spellings—use search_similar_executables.' It names both alternatives and the exclusion condition, leaving nothing to inference.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower, yet the description still adds real semantics: negative_lookup is exhaustive only if every declared source succeeded with exhaustive unrestricted coverage, absence otherwise remains unknown, and freshness may be unavailable because the partial scan is stored separately. That is substantive behavioral disclosure beyond the structured fields.

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?

Purpose is front-loaded in the first sentence, usage guidance follows, and no sentence is filler. The second sentence is clause-dense and jargon-heavy, which costs a little readability, but the information density is earned.

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?

An output schema exists, so return-value shape need not be restated; the description instead supplies the interpretive caveats an agent needs to read that output correctly (negative-result limits, registry non-probing, possibly-missing freshness). Nothing required to call or interpret the tool is missing.

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

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

Zero parameters, so the baseline is 4. The description reinforces this with "Call this with no parameters," leaving no ambiguity about how to invoke it.

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 ("Explain") and enumerates the exact facets of the resource it returns: snapshot provenance, source coverage, freshness, and negative-result limits. It also implicitly separates itself from the executable-lookup siblings by routing command lookups to check_executable. The resource itself is somewhat abstract domain metadata, which keeps it just short of a crisp 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?

Explicit when-to-use ("Call this with no parameters before interpreting a miss"), an explicit alternative ("use check_executable to look up a command"), and an explicit prohibition ("do not use coverage metadata as an existence result"). This is the full when/when-not/alternative triad.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, but the description adds non-obvious behavior: it reads one fixed snapshot with no live lookup, scope filters are ANDed over providers before null is decided, and null must be interpreted together with coverage_scope. That is real context the annotations cannot convey.

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

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

The record/snapshot behavior is front-loaded, and every clause carries information (routing, normalization, AND-filtering, null semantics). It is a dense, run-on paragraph rather than a cleanly broken structure, which costs a point but wastes no words.

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

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

For a single-record read with an output schema already documenting the return shape, the description supplies everything the agent still needs: exact-match semantics, snapshot vs live lookup, and how null relates to coverage_scope.

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%, so the baseline is 3; the description nonetheless adds meaning beyond the schema by noting that 'name is not normalized' and by explaining that scope acts as an AND filter applied before the null determination, which the schema only describes as 'all supplied key-value pairs must match'.

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 first sentence states a specific verb and resource with scope: 'Return the canonical provider record for one exact indexed command name.' It explicitly distinguishes itself from the sibling check_executable, so an agent can route between them without opening either 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?

Explicit when-to-use ('inspect package, ecosystem, source, version, and provenance'), explicit alternative ('use check_executable for collision decisions'), and an explicit exclusion ('do not treat a null record as availability'). Both the alternative tool and the interpretation rule are named.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description adds substantial context beyond them: it never executes argv or probes package availability, and it enumerates outcome states (ready, ambiguous, unsupported, unverified, missing-index, incomplete-context) plus the fact that omitted target facts surface in required_context rather than being guessed.

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?

Core purpose is front-loaded, then routing, then behavioral guarantees. Dense but every sentence carries information; slightly run-on with the nested clause about required_context, keeping it out of the top band.

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 an output schema present, return-value detail is unnecessary, and annotations cover the safety profile. The description fills the remaining gaps: execution guarantees, failure-state vocabulary, and parameter interaction, leaving nothing an agent needs missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description nonetheless clarifies interaction semantics the schema does not: 'environment maps its package manager to a provider ecosystem before preferences.package narrows candidates.' That sequencing between environment and preferences adds real meaning.

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+scope: 'Resolve advisory install and invocation argv for one indexed command provider.' This clearly delineates it from resolve_installations (several) and check_executable (availability), so an agent can distinguish it from siblings without opening a 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?

Explicit routing: 'Use this after lookup for one known target; use resolve_installations for several commands, and do not use it for name availability—use check_executable.' Names both alternatives and the conditions that select them.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantive behavior: it never executes argv or probes package availability, duplicates are preserved, and input order is retained. Each result carries its own status, required_context, and verification—context the annotations cannot convey.

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

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

Front-loads the core purpose before routing guidance, and every sentence carries information (scope, alternatives, resolution order, no-execution guarantee). Slightly dense, but no filler sentences to cut.

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 batch tool with an output schema present, the description covers what an agent needs: scope, sibling routing, resolution mechanics, order guarantees, and the non-execution contract. Return-value detail is correctly delegated to the output schema, and the mention of per-result fields is a bonus.

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%, so the baseline is 3, but the description adds real meaning beyond the schema: the shared environment selects the ecosystem first, then preferences.package narrows each command independently, and names/environment are explicitly tied to per-command resolution. This relationship is not spelled out in 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?

States a specific verb and resource ('resolve advisory install and invocation argv for several commands on one target') and immediately distinguishes itself from siblings resolve_installation (single) and check_executables (availability). An agent can select this without opening a 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?

Gives an explicit positive condition ('when all commands share an environment and preferences'), names the single-item alternative (resolve_installation), and an explicit negative exclusion ('do not use it for availability—use check_executables'). Nothing is left to inference.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds substantial context beyond them: no live registry call, failure rather than partial data when the derived index is missing or corrupt, deterministic case-insensitive sort with case-sensitive tie-breaking, and that limit applies only after sorting.

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?

Front-loads the purpose and the sibling routing before the operational caveats. Dense but every sentence carries distinct information; the sorting/limit clause is slightly detailed but not 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?

With an output schema present, return values need no explanation, and the description covers the remaining gaps an agent needs: filter intersection behavior, non-live data caveat, failure mode, and ordering guarantees.

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%, so baseline is 3, but the description adds genuine cross-parameter semantics not present in the schema: all active filters intersect, ecosystem and scope.ecosystem must both match, and conflicting values return none. It does not add per-parameter syntax beyond that.

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 ('Discover indexed command names') plus the exact filter dimensions (prefix, length, ecosystem, provider). It explicitly differentiates itself from siblings: check_executable for exact collisions and search_similar_executables for confusable names.

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?

Gives explicit when-to-use ('this for exploration'), names two alternatives with their distinct conditions, and adds a when-not caveat ('Do not use an empty result to infer availability'). The routing guidance is unambiguous.

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

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

Annotations already cover read-only/idempotent/non-open-world, and the description goes well beyond them: it discloses that no live registry call is made, that results come from a fixed snapshot, that an empty list does not prove global absence, and the exact ranking order (edit distance, trigram similarity, then name). This is exactly the negative-result semantics an agent needs to avoid over-claiming.

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?

Front-loaded with the purpose and the routing rule, and every sentence carries information. The parameter sentence is somewhat dense and run-on, and the block indentation adds noise, but there is no 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?

With an output schema present, return values need not be described. Given that, the description is complete: it covers the fuzzy-vs-exact distinction, the snapshot limitation, negative-result caveats, and parameter interaction, leaving no material gap for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real pipeline meaning: name seeds case-folded trigram candidates, scope filters before scoring, and limit applies after ranking. That clarifies ordering effects (scope narrows the candidate pool; limit truncates the ranked output) that the schema alone does not convey.

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 (find) and resource (indexed command names) with an explicit qualifier: candidates that 'may be confused with one proposed name.' It implicitly separates itself from check_executable by characterizing this as fuzzy typo-risk search rather than exact lookup.

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

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

Gives explicit sequencing ('use this after an exact check for typo risk'), names the alternative tool for the other case ('use check_executable for exact existence'), and adds a prohibition ('do not substitute this fuzzy result'). Nothing about when to pick this tool is left to inference.

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