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

With no annotations, the description carries the full burden: it discloses that work is parallelized across multiple upstream APIs and that the call may take 10-15s, which is exactly the kind of latency expectation an agent needs for timeouts. It stops short of covering auth requirements or how partial failures from any one upstream are reported.

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 what the tool does, followed by usage sequencing, input format, latency warning, and an example — each sentence contributes a distinct fact with no repetition. Dense but not padded.

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

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

For a one-parameter aggregation tool with no output schema and no annotations, the description covers purpose, sequencing, input format, and latency. It omits any indication of the shape or sections of the returned analysis, which is the one remaining thing an agent would want before calling.

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 goes slightly beyond by restating accepted input forms and giving a concrete invocation example (analyze(repository='sst/opencode')) that makes the string format unambiguous. It doesn't add validation or edge-case semantics for the parameter.

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 specific verb and resource and enumerates exactly what is aggregated (GitHub metadata, SearchCode quality, DeepWiki architecture, CodeWiki sections) in a single call. It also positions itself against siblings by naming the 'surgical wiki/searchcode calls' it replaces, so an agent can distinguish it without inspecting schemas.

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 states when to use it — 'Start here for unfamiliar repos before surgical wiki/searchcode calls' — which names both the trigger condition and the alternatives. The only gap is no explicit when-not, but the sequencing guidance is stronger than most tools provide.

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

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

With no annotations, the description carries the full burden; it does disclose the backing sources (PkgSeer + jsDelivr) and the registry restriction, and 'List' implies a read-only operation. However it says nothing about recursion depth, pagination/truncation for large packages, or auth/rate-limit behavior, which matters for a listing 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 short clauses, front-loaded with the action and resource, then constraints, then an example. No filler sentences; every phrase carries information.

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

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

For a two-parameter listing tool with full schema coverage and no output schema, the core invocation info is present. The remaining gaps — whether listing is recursive, how results are shaped or limited, and what an empty result means — leave the agent guessing at behavior after the call.

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

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

Schema coverage is 100%, so both parameters are already documented; the description only reinforces them via the example 'code_files(spec='npm:express')' and the 'npm:express/src/' path form. That illustrates how spec and path combine but adds little beyond the schema text.

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 files in an indexed dependency' — and scopes it to a package path, with a concrete example call. It is distinguishable from siblings like code_read or searchcode by being a directory-listing operation over an indexed package, though it never explicitly contrasts itself with those tools.

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

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

'indexes npm/pypi/crates ONLY (github: specs rejected)' is an explicit exclusion that prevents a whole class of wrong calls. What is missing is the positive routing: nothing says to use code_read for file contents or searchcode for content search, so the agent must infer the alternative.

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 does carry real weight: it names the backing sources (PkgSeer + jsDelivr) and the supported registry allowlist, which explains why some specs fail. It does not say what is returned on a missing file, whether output is truncated, or confirm read-only/non-mutating 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?

Three short clauses, front-loaded with the core action, followed by the registry constraint and a runnable example. Dense and largely waste-free, though the 'PkgSeer + jsDelivr' fragment is jargon whose value to an agent is marginal.

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 full schema coverage and no output schema, the essentials are present: supported registries, path scoping, and a worked example. The remaining gap is return-value/error behavior, which is minor for a file-read operation but would help when a path or spec is invalid.

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 are already documented as 'registry:name[@version]' and 'file path within the package'. The description only reinforces this with a combined example call, adding little meaning beyond the schema — baseline 3 is appropriate.

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

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

States a specific verb and resource ('Read a file from an indexed dependency') and scopes it with 'package-scoped path', plus a concrete call example. It does not explicitly contrast with the closest siblings (code_files, code_search, searchcode), so an agent must infer that this fetches one file's contents rather than listing or searching.

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 a hard exclusion — 'indexes npm/pypi/crates ONLY (github: specs rejected)' — which prevents a whole class of misuse. It stops short of naming an alternative for the rejected github case, leaving the agent to guess whether searchcode or docs should handle that.

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 must carry behavioral burden, and it does disclose useful traits: two backends, keyless Sourcegraph access, and that PkgSeer only covers npm/pypi/crates. However it says nothing about rate limits, result caps/pagination, latency, or what a result record contains, which matters for a multi-backend search.

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 compact sentences plus a worked example, with the dual-scope distinction front-loaded. Every sentence contributes; the example earns its place by demonstrating the target syntax concretely.

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, so the description must cover everything. It explains routing between backends well but leaves return-shape, result limits (beyond the schema's `limit` field), and ranking behavior unaddressed for what is effectively a federated search tool.

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

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

Schema coverage is 100%, so the schema already documents `query`, `target`, `source`, `lang`, and `limit` thoroughly. The description adds a concrete call example and mentions qualifiers, though its `kind:`/`category:` list is a looser/partly divergent restatement of the schema's `kind:`/`lang:`/`path:` qualifiers. 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 ('Search') and resources (code, docs, symbols) with two distinct scopes: package-scoped indexes via PkgSeer and global public repos via Sourcegraph. It does not name alternative sibling tools in the description itself (the `searchcode`/`analyze` routing hint lives only in the schema's `target` field), so it stops short of full sibling differentiation.

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?

Clearly explains the selection rule between modes: supply `target` for package-scoped search, omit it for global public-repo search via the keyless Sourcegraph path. It also constrains PkgSeer to npm/pypi/crates, so the agent knows the boundary. No explicit 'use X instead' routing for siblings appears in the description text.

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 usefully discloses the default fallback order and quota-free-source preference, but it does not explain the behavior of the many devdocs/rtd/context7 actions, permissions, rate limits, or return characteristics.

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 short, front-loaded, and free of filler. It could be slightly tighter because "Documentation operations" largely restates the tool name, but overall it is efficient.

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?

This is a high-complexity tool with 11 parameters, 14 actions, no annotations, no output schema, and low schema coverage. The description covers the default search path and follow-up reads but omits most action semantics and parameter meaning, so it is not complete enough for reliable invocation across all modes.

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 only 27%, so the description needs to compensate. The example clarifies query and library, but it leaves fast, path, slug, project, version, and most action enum values unexplained, including the 14 action options.

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 says this is for "Documentation operations" and clarifies that the default action performs a smart docs search with a fallback chain. That gives a usable sense of purpose, but it is broad for a 14-action tool and does not distinguish it from sibling search/documentation tools such as wiki, search_all, or search_package.

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 implies usage by describing the default fallback search and by recommending fetch(url) or devdocs_fetch_content after finding docs. However, it gives no explicit guidance on when to use docs instead of sibling tools or when to choose among its many non-default actions.

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 full burden and does disclose the core behavior: it fetches page content, deduplicates, and reranks by relevance. It does not describe failure handling for unreachable URLs, timeouts, fetch volume limits, or what the returned structure looks like, which matters for a network-fetching transform.

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 compact sentences: purpose first, input contract second, example last. Every element is front-loaded and earns its place, and the inline example resolves ambiguity about result shape without padding.

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

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

The description covers the input contract well enough to call the tool, but with no output schema it should explain what enrichment returns (e.g., full text field per result, ordering guarantees), and it leaves two parameters' relationship and fetch failure behavior unaddressed. Adequate but with clear gaps for a 5-parameter transform tool.

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

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

Schema coverage is 80%, so baseline is 3. The description reinforces that 'results' should come from a search tool and that 'query' is the original query, and the example clarifies the minimal result shape (url, title), but it does not explain the distinction between top_k and max_fetch_size or the meaning of include_html beyond what the schema already says.

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 pipeline verb set (fetch, deduplicate, rerank) over a specific resource (a list of search results), which is far clearer than the vague name 'enrich'. It implicitly distinguishes itself from the search_* siblings by being a post-processing step, but never names a sibling or explicitly contrasts with them.

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

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

It gives a clear usage context: pass results from any search tool plus the original query, which effectively tells the agent this runs after a search. There are no explicit when-not-to-use conditions or named alternatives, but the ordering dependency is clear from the phrasing and example.

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

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

With no annotations provided, the description carries the full behavioral burden. It does not disclose whether the tool is read-only, what authentication or rate limits apply, what the return structure looks like, or how pagination/count behaves. The example shows a search call but does not cover behavior for item, stories, or user actions.

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

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

The description is compact and front-loaded: resource and capabilities first, usage guidance second, and a concrete example last. Every sentence contributes information without repetition.

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

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

For a ten-parameter, multi-action tool with no annotations and no output schema, the description is too thin. It does not explain which parameters apply to which action, what each action returns, or the behavioral constraints an agent would need to invoke it correctly across search, item, stories, and user modes.

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 only 10%, so the description needs to compensate for ten largely undocumented parameters. It mentions query, tags, and min_points only through an example, and gives no meaning for action values, item_id, username, count, min_comments, sort_by_date, or firebase_type.

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

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

The description clearly identifies Hacker News and enumerates supported capabilities: search, item detail, user profile, and story lists. It distinguishes itself from so_search for resolved Q&A, though the multi-action scope means the exact mapping of actions to parameters is not fully clear from the description alone.

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

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

It provides a clear usage context (tech-community discussion and sentiment) and explicitly routes resolved Q&A use cases to the sibling tool so_search. It does not explain when to use each of the four action modes over the others, leaving some selection ambiguity.

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 must carry the full behavioral burden. It usefully discloses the multi-source fallback order (S2→arXiv→OpenAlex→CORE) and that arxiv_search is rate-limited, but it does not explain key behaviors such as pagination, what details returns, or what batch requires.

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 short, front-loaded with the source identity, and immediately follows with the preferred action and a concrete example. It is efficient, though the example uses only a small part of the tool's surface.

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?

This is a broad multi-action tool with 12 parameters, 14 enum values, no output schema, and no annotations. The description only covers search and arxiv_search, leaving most actions and parameters unexplained, which is insufficient for correct invocation of the full tool.

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

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

Schema description coverage is only 33%, so the description should compensate. It only hints at query and fields_of_study via an example and does not explain year, count, paper_id, author_id, paper_ids, open_access, offset, or the negative/positive IDs used by recommendations_negatives.

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

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

The description clearly identifies the resource: academic papers aggregated from Semantic Scholar, CORE, and arXiv. It distinguishes action=search from arxiv_search, but does not differentiate this tool from siblings like search_all or so_search, which are also search-oriented.

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 explicitly recommends action=search for topic queries and contrasts it with the single-source, rate-limited arxiv_search. However, for a tool with 14 actions, the other actions (details, batch, citations, references, recommendations, author_search, etc.) receive no guidance on when to use 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?

No annotations are provided, so the description carries the full burden. It discloses that this is a lightweight network reachability check and needs no parameters, but it does not explain return values, timeout/failure behavior, or whether any side effects exist.

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

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

The description is front-loaded and very short, with the purpose and usage condition stated immediately. The final ping() example is minimally redundant but harmless.

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 purpose and usage are clear. However, because there is no output schema, the description should ideally explain what a success or failure result looks like, and it does not.

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 has zero parameters, and the description confirms no parameters are needed, matching the empty schema. For a zero-parameter tool, this is the expected 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 specific verb and resource: it verifies reachability of the internet and key API endpoints. That scope clearly distinguishes it from the sibling search, docs, code, and analysis tools.

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

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

It explicitly says to use this before expensive calls when connectivity is uncertain, which gives a clear usage condition. It does not provide a when-not condition, but no sibling tool appears to offer an equivalent connectivity check.

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 load, and it does add real behavioral context: info is a composite of Libraries.io, Sonatype and PkgSeer (implying federated upstream calls), and upgrade_review bundles vulns + changelog + dependency diff. It does not disclose auth needs, rate limits, upstream failures, or whether operations are read-only, which matters for a 10-param network-backed 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?

One dense, front-loaded sentence packs the action inventory, then a routing rule to the alternative, then a minimal example — no filler. Structure matches how an agent reads: what it is, when to use something else, how to call it.

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 five-action, ten-parameter tool with no output schema and no annotations, the description never indicates what each action returns (fields in a composite info result, changelog entry shape, dependency diff format) or how failures surface. Action coverage is complete, but return-value and error context are absent, which is a meaningful gap given the multiplexing.

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 70%, and the description adds the action-to-parameter mapping the schema does not state as a whole: files/read use path, changelog uses version ranges and count, upgrade_review uses current/target version. The example ('pkg(name=..., action=...)' with the default info) also clarifies the minimal call. Gaps remain on registry='auto' semantics and on version defaults per action.

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?

It names a specific resource (package intelligence) and enumerates all five supported operations (info, changelog, upgrade_review, files, read) with parenthetical scope for each, so the agent knows exactly what the tool can do without opening the schema. It also explicitly distinguishes itself from the search_package sibling for raw single-registry queries.

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 carves a clean boundary against search_package ('for raw single-source registry queries ... use search_package instead') and gives a concrete call example. It stops short of explicit selection rules among the five actions — e.g. when upgrade_review beats changelog + info — leaving that to inference from the parentheticals.

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

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

With no annotations, the description carries the full burden. It does add genuine behavioral context — 14+ sources, embedding dedup, reranking — but says nothing about cost/latency of fanning out to all sources, per-source failure behavior, result ordering, or that synthesis silently no-ops without GROQ keys (that only appears in the schema). Adequate, with real gaps for a 12-parameter fan-out 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?

Two front-loaded sentences plus a compact example; the routing guidance precedes the example and nothing is redundant. Every element 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?

Routing is complete, but for a 12-parameter tool with no annotations and no output schema the description leaves the result shape unexplained (merged ranked list vs. per-source groups) and does not cover parameter interplay. Enough to call it, not enough to call it correctly in every case.

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 only 50% across 12 parameters, so the description must compensate and largely does not. The lone example only exercises query and language; it never clarifies how repo/owner, library/version, fromdate/todate (Stack Exchange-only), or fields_of_study map to particular sources, which is the main source of misuse risk.

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 ('Unified search across 14+ sources') plus the differentiating mechanism (embedding dedup and reranking). It explicitly distinguishes itself from the single-source siblings so_search/hn/papers/code_search, so an agent can pick it without opening any 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?

Names the selection rule directly: use this for 'broad multi-source discovery', use the single-source tools for 'surgical single-source work'. That is an explicit when/when-not plus named alternatives, and the inline example reinforces the intended shape of a call.

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 helpfully discloses that the service is free, requires no auth, and has no rate limits, which is useful context. However, it does not state that operations are read-only, describe return format or pagination, or explain failure modes.

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

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

The description is front-loaded with the core purpose and then routes through the action modes compactly in a single sentence, followed by a short example. It is efficient, though the action enumeration is dense and could be slightly more scannable.

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 14-parameter tool with no output schema and no annotations, the description plus full schema coverage gives an agent enough to select an action and invoke it. The main remaining gap is that response shape and output behavior are not described, but the action routing and auth/rate-limit context cover most needs.

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 every parameter is already documented, including enums and defaults. The description adds only the example usage ('action=analyze', 'repository=...'), which repeats what the schema already conveys. Baseline 3 is appropriate.

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

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

The description states a specific capability ('Per-repo code intelligence via SearchCode') and enumerates the five action modes with their purposes. It is clear what the tool does, but it never distinguishes itself from sibling tools such as code_search, code_read, or analyze, which likely overlap.

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 explicit routing guidance for each action ('Use analyze for instant repo overview... search for searching code... findings for code quality issues...'), plus a concrete example. It lacks any when-not-to-use guidance or comparison against the overlapping sibling tools.

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 mentions Libraries.io metadata and source rank, but does not disclose read-only behavior, authentication requirements, rate limits, pagination, result caps, or how the many action modes behave.

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

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

The description is front-loaded with the data source and use cases, then gives a compact example. Every sentence earns its place, and there is no redundant or filler content.

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 13-parameter, multi-action search tool with no annotations, no output schema, and low schema description coverage, the description is too thin. It does not explain action modes, return values, result limits, or most parameters, leaving an agent unable to invoke it confidently beyond simple name/platform searches.

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 only 15%, so the description must compensate for 13 mostly undocumented parameters. It gives one example using name and platform and vaguely implies the repo parameter, but omits sort, count, owner, query, version, keywords, licenses, languages, and the full meaning of the action enum.

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 identifies Libraries.io dependency metadata and source rank, and states concrete use cases: comparing dependency candidates and finding the repo behind a package. It distinguishes itself from search_package/pkg/vulns for registry versions and vulnerabilities, though it does not explicitly frame itself as a search verb or fully define scope.

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

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

It gives clear usage guidance for selecting this tool when comparing dependency candidates or finding a package repo, and explicitly routes registry versions/vulns to search_package/pkg/vulns. It does not cover exclusions against every relevant sibling, but the main alternative is 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?

No annotations are provided, so the description carries the full burden. It does not state that all these operations are read-only, whether there are registry rate limits or auth requirements, how errors/unknown packages surface, or what the 'raw' response looks like; 'raw' hints at unprocessed payloads but is never explained.

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 compact sentences, front-loaded with the resource scope, then the sibling routing, then an example. Slight redundancy between the title-like first clause and the example, but 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?

For a tool with 7 parameters and a 21-value `action` enum spanning versions, readme, advisories, deps.dev hashes and reverse dependencies, the description says nothing about output shape or how the action families differ in what they return. The pkg routing helps, but an agent must open the schema to understand the action surface.

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 71%, so most parameters are already documented, and the description's example (name='express', registry='npm') mainly restates the schema. It adds a routing note in the schema for full metadata ('use pkg'), but contributes no new meaning about `action` groupings, `version='latest'` resolution, or how `registry='auto'` resolves.

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 the resource and scope precisely: 'Raw package registry queries (npm/PyPI/crates + deps.dev)', which tells an agent exactly what data source it hits. It distinguishes itself from the `pkg` sibling, but the verb is generic ('queries') and the tool name implies search while the description covers a broad action surface (versions, readme, advisories, reverse deps), so the exact operation set is only clear from 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 states the selection condition — 'Use for fast single-source lookups' — and names the alternative with the condition that selects it: 'For composite intelligence (Libraries.io + Sonatype vulns), use `pkg` instead.' It even supplies a concrete invocation example, 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the Stack Exchange rate limit (300 req/day), SOFA beta status, and SOFA_KEY environment requirement, but it does not describe pagination behavior, output shape, or whether all sub-actions are read-only.

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

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

The description is compact and front-loads the key distinction between the two backends. The example is useful rather than filler, though the first sentence is dense with parenthetical detail.

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 19-parameter tool with no output schema and no annotations, the description is not complete enough. It covers the main backend choice and some operational constraints, but it omits how the many sub-actions interact with parameters, pagination, and return values.

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 only 53% for 19 parameters, and the description compensates only partially by explaining the action backends and giving an example using query, tags, and accepted. Many parameters such as site, sort, type, count, closed, answers, question_id, and content_type remain undocumented in the description.

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 identifies Stack Overflow as the resource and distinguishes the two backends, Stack Exchange and SOFA, with specific attributes like resolved answers and trust scores. It is clear what the tool does, though it does not explicitly differentiate from sibling tools such as search_all or code_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?

It explicitly states when to choose stackexchange versus sofa: authoritative resolved answers versus fresher agent-contributed content. It gives an example call, but does not explain when to use this tool instead of sibling tools like search_all or code_search.

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 burden and does disclose meaningful behavior: an auth/capacity failure mode (401/429/quota) and an automatic keyless fallback path, which materially affects trust in results. It omits return shape and any indication of rate limits or latency beyond the quota mention.

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?

Dense but front-loaded: the source/fallback framing leads, per-action requirements follow, and the concrete example at the end earns its place by showing correct invocation. Slightly run-on in the middle clauses but no filler sentences.

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 7-parameter, zero-required multi-action dispatcher with no annotations and no output schema, the description covers invocation requirements well but never indicates what each action returns or how results differ between Sonatype and the OSV.dev fallback. Adequate for calling the tool, incomplete for interpreting its output.

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 does map most parameters to actions: name/version/platform/coordinates for scan, purl for latest_version and license, and id formats (Sonatype, GHSA-*, CVE-*) for vuln_id in detail. Remaining gaps are the valid platform values and purl syntax, neither of which is documented anywhere.

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 specific verbs and resources (scan packages, vulnerability details, latest version, license analysis) and enumerates the action modes, so the agent knows the tool's scope without opening the schema. It does not, however, contrast itself against close siblings such as search_package, pkg, or enrich, which also deal with 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?

Gives per-action preconditions explicitly: 'scan needs platform+name+version (or coordinates)' and 'latest_version/license need purl', plus the automatic OSV.dev fallback on Sonatype 401/429/quota errors. That's clear when-to-use context for each mode, though there are no explicit when-not-to-use rules or sibling routing.

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, but it does not disclose whether operations are read-only, what each action does, permission or auth requirements, rate limits, or what result shape to expect. It only adds a multi-repo limit of 10, which is useful but insufficient for a nine-parameter multi-action 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?

The description is short and front-loads the core-purpose statement, then follows with practical parameter guidance and a concise example. It is efficient, though the example focuses only on the ask path and does not structure the remaining actions.

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 nine parameters, a required action enum, no annotations, no output schema, and very low schema description coverage, the description is materially incomplete. An agent still cannot confidently determine how to use search, fetch, ask, and architecture, or how most parameters interact.

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 only 11%, so the description needs to compensate, and it does explain owner+repo versus repos and gives a question example. But it leaves the required action enum entirely unexplained and provides no guidance on query versus question, wiki_name, limit, or offset.

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 identifies the resource and source systems clearly: repo architecture and wiki content via DeepWiki and CodeWiki. However, it frames the tool with multiple action modes (search, fetch, ask, architecture) without clarifying what each mode does, and it does not explicitly differentiate this tool from siblings such as docs or code_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?

It gives useful parameter-selection guidance for single-repo versus multi-repo use cases and includes an example, but it does not state when to use this tool instead of alternatives like docs or code_search, nor does it explain when each action value should be chosen.

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