silica-core

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavioral context on top: static AST only, no repo mutation between calls ('same repo state, same bytes'), an enforced character budget with the target always served, and the `truncated`/`dropped` signals an agent must check before trusting completeness. It also discloses that `languages` reports which parsers this install supports — an environment-dependent limitation.

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 tightly packed sentences with the usage trigger front-loaded and no filler. The telegraphic style ('Static AST only, same repo state, same bytes') and heavy inline backticks make it slightly harder to parse than it needs to be, costing a point on structure.

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

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

With no output schema, the description carries the full burden and discharges it: it enumerates the sections returned, explains the budget/truncation contract, names the meta-fields (`truncated`, `dropped`, `languages`), and states the static-analysis limitation. Nothing an agent needs to call and interpret this tool is missing.

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

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

Schema coverage is 100%, so target forms, section names, and the budget default are already documented in the schema. The description reinforces the budget concept ('inside a character budget', 'target is always served') but adds no syntax, format, or default details beyond what the schema states, so the baseline 3 applies.

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

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

The description names a specific resource — a 'pack' of structural facts (supertypes, extenders, callers, named signatures, external dependencies, importers) around a file, a `#Class.member`, or the symbol at `#L<line>` — and explicitly scopes it against the sibling tools' territory (raw file reading/searching). An agent can tell what this produces and when it differs from silica_read/silica_search without opening a schema.

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

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

It gives concrete triggers: 'before editing or explaining a source file' and 'when a traceback or a diff names `file:line`'. That is clear when-to-use guidance, but it never names an alternative tool (e.g. 'instead of silica_read') or states an exclusion, so it stops short of the explicit routing a 5 requires.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: what each status means, why a file is excluded or unconverted, the PDF-vs-sidecar indexing rule, the stale/unverifiable source_state semantics, and the cold index.state caveat. This is genuinely decision-relevant behavior that no structured field carries.

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?

It is long, but front-loaded with the motivating question and then information-dense: nearly every clause defines a distinct status or state rather than restating. Some parenthetical nesting makes it dense to parse, but little of it is filler.

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

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

With no output schema and no annotations covering return semantics, the description carries the full burden and does so: it enumerates all statuses, the reason fields, source_state values, and the cold-index edge case. An agent has enough to interpret the response correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description exceeds it by defining every value the status filter accepts (indexed, changed, excluded, failed, unconverted) and the meaning of each, plus the semantics of the empty-folder default, which helps the agent pick filter values rather than just names.

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 resource and scope ('Inventory of the root and what the index did with each file') with a precise taxonomy of per-file outcomes. It distinguishes itself from the read/search siblings implicitly ('before trusting a search'), but it never names itself as the listing/status tool in a single clean verb+resource clause, so the opening is slightly indirect.

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: consult this before trusting a search result or concluding a file is absent. That is real when-to-use guidance rather than vague framing, though it does not explicitly name silica_search/silica_read as the alternatives the agent would otherwise reach for.

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

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

Annotations only cover the safety profile (readOnly, idempotent, non-destructive); the description adds far more: continuation via `truncated`/`next_start`, PDF page size (~1.2k tokens), extract_path as a cache rebuilt when the PDF changes and outside any `version` guard, `source_state` values (stale, unverifiable), and the `error.unconverted`/`error.changed` failure modes. This is unusually rich disclosure for a read 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 lead sentence is well front-loaded, but the body is overstuffed: nested parentheticals, backticked tokens, dated measurements ("measured 2026-09-09"), and cache-internals details make it hard to parse for a read tool. Much earns its place, but the density and length cost 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?

There is no output schema, so the description must describe returns, and it does: outline, version, truncated/next_start, pages, page_map, extract_path, source, and source_state, plus the error cases. For a read tool whose annotations already cover safety, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the terse per-parameter descriptions already carry the baseline. The prose adds real meaning beyond them: `section="p. 8"` serves one PDF page, `version` is the served text's and never the original's, and `expect_version` is the carry-forward guard that refuses rather than reading different bytes under an old citation.

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+resource ("Read a located slice before citing it") and enumerates the four serving modes: line range, heading section, PDF page, or whole file under max_chars. It distinguishes read from search by role ("a search located" vs. "widen the search's width to explore"), though it never names the sibling silica_search outright, leaving the routing slightly oblique.

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

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

It states the core context clearly: use the read to pull the exact slice a search located so you can cite it, and points to search's `width` when you want to explore rather than cite. However there are no explicit exclusions or prerequisites (e.g., when to prefer silica_files), so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety and repeatability profile is covered. The description goes well beyond that by disclosing output semantics (matched_terms, coverage as idf mass, terms_absent, the dense-only leg with coverage 0), the absence of any boolean 'no answer', the PDF page/section behavior, and the section/span shape of source-tree hits.

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

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

Front-loaded with the decisive trigger before any mechanics, and nearly every clause carries unique information (ranking basis, grep exclusion, width/PDF advice, coverage semantics, symbol routing). It is still a long, unbroken block of prose with several parentheticals, which costs it the top mark.

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 compensates by naming the return fields and how to interpret them, describing the source-tree and PDF representations, and warning that no 'no answer' signal exists so the agent must read coverage and matched_terms. For a six-parameter search tool this is essentially complete.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents all six parameters. The description adds operational meaning for `width` beyond 'Characters in each hit's window' by explaining that the window is the densest `width`-char segment and that on a PDF hit one should widen it to 1200-1500 rather than reading the page, plus the fused-queries intent of ranking concept and identifiers separately.

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 concrete verb and resource (ranks passages, and in a source tree the functions/methods/classes/constants, by the question's words and vectors) and pins the exact scenario that selects it: a question naming no identifier. It explicitly contrasts itself with grep, Glob and Read, so an agent can tell it apart without opening the schema or sibling 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?

Gives explicit when-to-use ('For a question that names no identifier... call this before any grep, Glob or Read') and when-not ('Do not grep for the words of a question; grep for an exact string or a symbol name you already know'). It also routes follow-up work to silica_read for symbol bodies, leaving little 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 annotations only declaring the safety profile, the description adds the critical details: writes are atomic, a lint pass runs afterward and reports structural violations and unresolved wikilinks, overwrites are guarded by version/create_only checks, and rollback is git with no internal journal. That is substantial context beyond readOnlyHint/idempotentHint.

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 core action, then failure conditions, then the recovery model. Every sentence carries information an agent needs.

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 guarded write with full schema coverage and no output schema, the definition is nearly complete. The only residual ambiguity is whether lint results are returned by this call or require a separate invocation, since `lint` in backticks reads like another 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 expect_version, create_only, body decoding, and frontmatter are already documented. The description reinforces the refusal semantics of expect_version and create_only but adds no format or syntax detail the schema lacks. Baseline 3 applies.

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

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

States a specific verb+resource ('Write one note atomically') and immediately adds the post-write lint behavior. This cleanly separates it from read-only siblings (silica_read, silica_search, silica_files), none of which mutate notes.

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 'refuses to overwrite when expect_version does not match or when create_only is set and the file exists' clause tells the agent exactly when the call will fail and therefore which mode to pick for new vs. existing notes. It stops short of naming an alternative tool, but no write sibling exists to route to.

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