lookupd

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

With no annotations supplied, the description carries the full burden and does reasonably well: it discloses that rankings are provisional with no outcome evidence, that each result carries a runtime-specific install snippet, and that lookups are free. These are exactly the behavioral facts an agent needs to interpret and trust the output. It stops short of describing result cardinality behavior, latency, or error handling.

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?

Four short sentences, front-loaded with the purpose, then input guidance, then output expectations and cost. Nothing is padded or repeated from the title, and each sentence contributes a distinct fact.

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 six-parameter discovery tool with no output schema, the description covers purpose, input phrasing, result ranking caveat, and result contents (install snippet) plus cost. The main remaining gap is that the return record's identifying fields are not named, which would help an agent chain into get_entry.

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 six parameters including enums and bounds; the baseline is 3. The description adds marginal value by stressing the short-phrase form of 'task' and by linking 'runtime' to the install snippet, but it says nothing about kind, capability, max_results, or verified_only beyond what the schema states.

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

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

The description opens with a specific verb and resource: 'Find MCP servers that provide a capability for a task.' That is far more informative than the title alone and tells an agent exactly what kind of lookup this is. It does not explicitly contrast itself with siblings like get_entry or report_outcome, so an agent must infer that this is the discovery step and get_entry is the detail step.

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 useful input-level guidance: 'Pass a short capability phrase (e.g. "read Linear issues"), not the user's full request.' That steers query formulation well. However, the description gives no explicit when-to-use versus when-not guidance relative to the sibling tools, and no prerequisites or follow-up path (e.g. use get_entry to inspect a result), so usage is only implied.

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 behavioral burden and does disclose real traits beyond the schema: the shape of the returned payload and, importantly, that ambiguous inputs produce a `matches` list ordered most-likely-first. That ambiguity handling is exactly the kind of behavior an agent cannot infer. It omits error behavior when nothing matches and does not state precedence among name/url/package.

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 most useful information (what you get back) is front-loaded, followed by the lookup-key options. Two sentences, no filler. The second sentence is dense with three distinct ideas but remains parseable.

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?

There is no output schema and no annotations, so the description must cover return shape and safety; it covers return shape adequately. However, with four optional parameters and no required key, an agent still cannot tell the precedence among name/url/package or what happens when nothing matches. Those are material gaps for a lookup tool whose main failure mode is an ambiguous or empty result.

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 75%, just under the threshold where the schema would do all the work. The description adds genuine meaning beyond the schema fields: it explains why url or package is acceptable (to resolve the registry name) and ties the undocumented `runtime` parameter to install-snippet selection. It leaves the runtime enum values themselves uninterpreted.

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

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

The description uses a specific verb and resource ('Full details for one entry') and enumerates the payload: raw server.json, install snippets, lookupd metadata. It also distinguishes the lookup modes (registry name vs. url/package), which separates it from find_capability and health. It does not explicitly name those siblings, so it falls just 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?

It gives clear positive guidance on which key to pass depending on what the agent has: a registry name, or a remote url / npm/PyPI package from an existing MCP config. It even explains the downstream purpose ('that finds the registry name to use with report_outcome'). It stops short of explicit when-not-to-use or precedence rules among the three keys.

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 supplied, the description carries the full burden and does reasonably well: it discloses that this performs an active probe of a remote endpoint, the full set of result states including auth_required, the metrics returned (7-day uptime, median latency, tool count, last probe), and the hard limitation that stdio-only servers are not probeable. It does not say whether results are live or cached, nor whether probing has side effects or rate limits, which keeps it below a 5.

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 the probe action first, then the result vocabulary, then the metric list, then the exclusion. Dense but every clause adds information; the only mild cost is the packed enumeration of return fields.

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, no-annotation, no-output-schema tool, the description covers what is checked, the possible states, the metrics returned, and the non-probeable case. The remaining gaps — live vs cached results, behavior on unknown names — are minor and do not block 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 description coverage is 0%, so the description must compensate, and it only indirectly implies that the single parameter identifies the entry ('of an entry'). Given one obvious required name parameter this is adequate, but it adds no format, matching, or error semantics (e.g. what happens for an unknown name).

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 ('Probe status of an entry') and enumerates the observable states (up, auth_required, down, dead), so an agent knows exactly what the call reports. It stops short of differentiating from the sibling get_entry, which likely also takes an entry name and returns entry data, leaving a small ambiguity about which to call.

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?

Usage is implied rather than stated: the agent can infer this is for checking liveness/auth state, and the 'Stdio-only servers are not_probeable' clause usefully excludes a whole category of entries. However, there is no explicit 'use this instead of get_entry when…' guidance and no mention of what to do for a non-probeable entry.

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 and does disclose meaningful behavior: the report feeds rankings ('Rankings improve from these reports') and there is a hard privacy constraint ('never task text, prompts or paths'). It does not state whether duplicate reports are deduplicated/enforced, what error or return behavior to expect, or any auth requirement, so it falls short of fully transparent for a write-like 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?

Three dense sentences, front-loaded with the when-to-report rule before the parameter and privacy details; every sentence carries information. The backticked field list is a bit packed but not wasteful.

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 six-parameter reporting tool with no annotations and no output schema, the description covers what to report, how often, how to resolve the identifier, and the privacy boundary. Remaining gaps (response shape, dedupe/error behavior) are modest given the tool's narrow, fire-and-forget purpose.

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

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

Schema description coverage is 0%, so the description must compensate. It defines `entry` precisely (registry name, sourced from get_entry via url or package) and flags `success` as required, and it enumerates the allowed structured fields, but capability_tag, latency_bucket, runtime, and error_class are only named, not explained beyond their self-describing enum values.

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

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

The description opens with a specific verb and resource plus scope: 'After a task used an MCP server, report once per server whether it worked.' It also distinguishes the two source cases (servers found via lookupd vs. already installed) and names the get_entry sibling as the way to obtain the entry name, so an agent can tell what this tool is and is not.

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?

Timing ('after a task used an MCP server'), cadence ('once per server'), coverage ('servers found via lookupd ... and servers already installed alike'), a prerequisite (use get_entry with url or package for installed servers), and an explicit skip condition ('skip the report if there is no entry') are all stated. Little is left to inference about when to call this versus get_entry.

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