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

With no annotations, the description carries the full disclosure burden. It usefully reveals the retrieval pipeline and the required LLM credentials, which is real operational context an agent needs. It omits what happens when those env vars are absent (failure mode), expected latency/cost of LLM calls, and whether the call is purely 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?

Two tight sentences, front-loaded with the core purpose before the pipeline detail and the env prerequisite. No filler, though the pipeline jargon is dense for the value it adds to tool selection.

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

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

There is no output schema, and the description does say the result is a cited answer, which covers the most important return-value question. However, the response shape (answer string vs. object with citations), parameter meanings, and failure behavior under missing credentials are all left to guesswork for a 3-parameter 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 0%, so the description must compensate and it largely does not: site_id, question, and top_k (default 4) are all undocumented. Only 'site_id' is obliquely covered by 'the site's pages'; top_k's meaning (retrieval candidates? reranked results?) is left entirely unexplained.

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+resource: answers a question grounded in the site's pages, returning a cited answer, and it names the mechanism (keyword retrieval + graph-neighborhood expansion, embedding rerank). This is far more informative than the bare name 'ask'. It never explicitly contrasts with siblings like search or neighbors, though the 'cited answer' framing implies the distinction.

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 only implied: an agent can infer it should use this when it wants a synthesized, cited answer rather than raw pages from search/get_page. The one explicit guideline is an environmental prerequisite (SITE_KG_LLM_BASE / SITE_KG_LLM_KEY), not a when-to-use rule. No exclusions or alternative routing are stated.

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 exist, so the description carries the full burden. It does disclose the return payload (markdown body plus title and source URL), which is useful given there is no output schema, but it says nothing about truncation, missing/invalid page IDs, permission scope, or whether 'full' is actually full.

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 compact clause with the most important information (full markdown content) front-loaded and no filler. It borders on under-specification rather than verbosity.

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

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

With two undocumented parameters and no output schema, the description should at minimum explain how to obtain the IDs and what the response looks like. It partially covers the return shape but leaves the input contract entirely implicit.

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 0% — both site_id and page_id are bare strings with no descriptions. The description mentions only 'one page' and adds nothing about ID formats, how site_id scopes the lookup, or whether IDs come from search/list_sites results.

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 the resource precisely (one page) and the payload (full markdown body, title, source URL), which distinguishes it from bulk siblings like search and list_sites. It lacks an explicit verb ("get"/"retrieve") and never names an alternative, but the scope is unambiguous.

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

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

No indication of when to use this versus search, neighbors, or render_site, and no preconditions stated. The agent must infer from the name alone that this is the single-page fetch after an ID is known.

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 substantial work: it explains what edges each file class contributes, defines the READY/NOT-READY verdict and its one caveat (content-derived edges still run when the verdict is NOT-READY), and discloses the return payload (site_id + verdict). Gaps remain around cost/duration for large directories, idempotency of re-ingestion, and failure behavior on bad paths.

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 purpose sentence is front-loaded and the file-type/edge breakdown follows logically. The relations paragraph is dense but each clause carries distinct information. Slight over-density in the closing sentence about content-derived edges and the verdict, which restates the caveat twice.

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 4-parameter mutation tool with no annotations and no output schema, the description covers the return value and the relation model well. It falls short on `max_files` (what happens when exceeded — truncation? error?), `respect_gitignore` semantics, and whether ingesting the same path twice duplicates or replaces the graph — all decision-relevant for an agent.

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 does so thoroughly for `relations`, enumerating every accepted value ('auto', 'llm', 'all', 'off', explicit comma list) and the env-var fallback chain — information found nowhere in the schema. However, `path`, `max_files` (default 2000), and `respect_gitignore` (default true) get zero explanation, leaving half the surface undocumented in both places.

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?

Specific verb + resource + scope: 'Build a knowledge graph from a local directory of docs and/or code files.' The word 'local' implicitly separates it from the ingest_url sibling, and it enumerates the supported file types, so an agent knows exactly what corpus this accepts.

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 conditional guidance inside the output contract — 'NOT-READY ... use search' tells the agent what to do after a link-less corpus — and the relations defaulting rules ($SITE_KG_RELATIONS, then 'auto') are spelled out. But there is no explicit when-to-use-this-vs-ingest_url statement and no stated preconditions (does the site need to exist first, does it replace or append to an existing graph?).

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 discloses important behavior: it returns a READY/NOT-READY graph-quality verdict, explains the `relations` modes, and warns that `dev` ignores robots.txt and politeness delays and forces `respect_robots=False`. It stops short of describing registration side effects, idempotency, or permissions beyond the authorization warning for `dev`.

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

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

The description is front-loaded with purpose and return values, then covers the two highest-risk parameters. It is somewhat long, but each paragraph adds useful operational context rather than repeating structured 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 complex seven-parameter ingestion tool with no annotations and no output schema, the description gives solid high-level context, return behavior, and safety notes for `dev`. It remains incomplete because several crawl-scope and concurrency parameters are undocumented, which matters 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 description coverage is 0%, so the description must compensate for all seven parameters. It adds meaningful detail for `relations` and `dev`, but leaves `url`, `max_depth`, `max_pages`, `concurrency`, and `respect_robots` largely or entirely unexplained beyond the schema's names and defaults.

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: it crawls a website, builds a knowledge graph, and registers it as a queryable site. This clearly distinguishes the tool from siblings such as ingest_local, and it also states the return values (site_id and graph-quality verdict).

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 intended use is implied by 'Crawl a website' and by the note that `dev` is for sites the caller owns or is authorized to test. However, it does not explicitly say when to choose this tool over ingest_local or other siblings, nor does it state when not to use it.

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 disclosure burden; it does reveal a useful scope constraint (only already-ingested sites are listed) and the fields returned. It says nothing about ordering, result size, pagination, or cost, which matters for an unfiltered list over an unknown corpus.

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 ten-word sentence that front-loads the verb and resource and adds only the fields worth knowing. Nothing wasted, nothing buried.

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 zero-parameter list tool with an output schema covering return values, the description is nearly sufficient: what is listed and what accompanies each entry. The only missing piece is ordering/result-size guidance, which is minor here.

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

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

The tool takes zero parameters, so there is no parameter semantics for the description to explain and the baseline of 4 applies.

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

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

States a specific verb (List) and resource (ingested sites) and even names the returned fields (verdicts, graph sizes), so the agent knows exactly what it gets. It does not explicitly differentiate itself from the sibling site_stats, which likely covers similar ground, so it falls short of a 5.

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

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

There is no statement of when to call this versus site_stats (aggregate stats?) or search (filtered lookup). The agent must infer usage entirely from the name and one-line purpose.

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 exist, so the description carries the full disclosure burden. It usefully reveals a behavior the schema does not: depth is capped at 2, a real constraint an agent needs. However it says nothing about what the subgraph contains (node properties, edge direction, truncation of large neighborhoods) or cost/latency, which matters for traversal tools.

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 short sentences with the core behavior first and the routing hint second — no filler. It is arguably under-written rather than bloated, but structurally it is tight and front-loaded.

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

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

With no annotations, no output schema, and 0% parameter coverage, two sentences are not enough: the return shape of the subgraph, the meaning of the identifiers, and the depth default are all absent. Adequate to guess at the call, insufficient to call it confidently.

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 all meaning must come from the description, and it only addresses `depth` — giving the hop semantics and the cap of 2. `site_id` and `page_id` remain bare names with no indication of format, and the depth default of 1 is not mentioned.

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-in-effect (retrieve the subgraph) and resource (pages neighboring a given page), scoped by `depth` hops. An agent can tell it apart from get_page (single page) and search (query-based retrieval). It never spells out 'neighbors of' in the schema sense, but the wording is concrete enough to act on.

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?

'Use after search to expand context' gives one concrete triggering condition and names the preceding sibling tool. There is no guidance on when not to use it (e.g. versus get_page for a single known page) or on what the result is good for beyond generic 'context'.

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 useful traits: it produces a file and "Returns the file path," and it requires a WebGPU-capable browser. It does not say whether the output file is overwritten, whether rendering is slow/expensive, or whether it replays ingestion or only existing data.

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 purpose is front-loaded in the first clause, then the visual sequence, then the return value and the environment requirement. Dense but every sentence carries information; the middle replayed-build sentence is long but justified by the tool's unusual visual semantics.

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?

Return value is stated (file path) and the browser prerequisite is called out, which covers the two things an agent most needs for a render tool with no output schema. Gaps remain around the site_id parameter, cost/runtime, and how it relates to render_site, making it adequate but not complete.

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

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

Schema coverage is 0% and the sole required parameter site_id is never mentioned in the description, so nothing is added beyond the bare schema field name. The agent must infer that site_id comes from list_sites and what a 'site' means here.

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?

Specific verb+resource: "Render the graph construction process as a self-contained WebGPU viewer," with concrete detail on what is visualized (chapter rings, evidence edges, per-dimension waves, HUD counters). It does distinguish itself from the query siblings by scoping itself to human inspection, but it never names or contrasts with render_site, the closest sibling.

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 frames itself as the "human inspection path" and states that "AI-facing queries stay on search/neighbors/ask," which is real when-not-this-tool guidance. The obvious remaining alternative, render_site, is not mentioned, so the agent must infer which renderer to pick.

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

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

No annotations exist, so the description carries the full burden. It does well on output shape (archive returns a file path; mode=live returns {live_url, run_id, last_seq} over a loopback SSE server), but says nothing about side effects such as file writes, server lifetime/cleanup, or whether max_nodes truncates silently.

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 tight sentences, front-loaded with the purpose and the human-vs-AI routing decision, with no filler. Dense jargon ('loopback SSE server', 'last_seq') is used without unpacking, which costs a bit of readability.

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

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

With no annotations and no output schema, the description does the heavy lifting on purpose, mode semantics, and return values. It still leaves three of four parameters undefined and omits operational details (server lifecycle, truncation, permissions), which matters for a tool that both writes a file and opens a local server.

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 0% and the schema supplies only bare titles and defaults, so the description must compensate. It fully explains `mode` (archive vs live) and ties it to distinct return values, but site_id, scene, and max_nodes get no meaning at all — max_nodes in particular could imply truncation behavior that is left unstated.

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 ('Render the graph as a self-contained HTML viewer') and frames it as the human inspection path, which separates it from the search/ask/neighbors tools. It does not distinguish itself from the sibling render_build, so an agent cannot tell which renderer to pick 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?

Explicitly routes AI-facing queries away to search/ask/neighbors, giving a clear when-not-to-use rule alongside the 'human inspection' use case. The missing piece is a comparison to render_build, the other rendering sibling, which 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the inverted-index and idf-weighting approach, but says nothing about permissions, result ordering, pagination, rate limits, or what happens when a site is missing. For a search tool with no annotation coverage, this is thin operational context.

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

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

The description is a single front-loaded sentence with no wasted setup. The parenthetical algorithm detail is concise, though not especially useful for deciding how to call the tool.

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

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

With three parameters, 0% schema coverage, no annotations, and no output schema, the description should do more to explain inputs and behavior. It gives only the core retrieval concept and leaves usage, parameter meanings, and operational behavior largely unspecified.

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, but it does not define any parameter. 'Site's pages' weakly implies site_id and 'full-text search' weakly implies query, while limit is entirely undocumented in both schema and 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 states a specific verb and resource: 'Full-text search over the site's pages.' It clearly communicates keyword-style retrieval and even names the indexing approach, but it does not explicitly distinguish itself from siblings like 'ask' or 'get_page'.

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 phrase 'full-text search' implies usage for keyword lookup over site pages, but there is no explicit guidance on when to choose this over 'ask', 'get_page', or 'neighbors'. The agent must infer the selection conditions from the tool name and brief purpose statement.

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 usefully discloses the returned metrics and that the scope is one site, but does not state that the operation is read-only, what permissions are needed, or any cost/rate-limit 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?

One front-loaded sentence with a compact colon list; every element names a return metric or scope and 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?

For a simple one-parameter stats tool with no output schema, the description enumerates the returned fields, which is helpful. However, it leaves the site_id source/format unexplained and, with no annotations, does not cover read-only behavior or access requirements.

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

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

There is a single required site_id parameter with 0% schema description coverage, and the description only says 'one site' without explaining the ID format, source (e.g., list_sites), or validation. It adds almost no parameter-level meaning beyond the schema.

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

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

Names the resource (graph health for one site) and enumerates the exact metrics returned: doc/edge counts, edge types, verdict, top hubs. It is clearly distinct from siblings like get_page, neighbors, search, and list_sites, though it uses a noun phrase rather than an explicit verb.

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?

Implies the tool is for inspecting graph health metrics of a single site, but gives no explicit when-to-use guidance, no exclusions, and no alternatives such as neighbors or search for related queries. An agent must infer the selection context.

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