Skip to main content
Glama
kiycoh

silica-core

by kiycoh
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

silica_files

Read-onlyIdempotent

List workspace files with index status (indexed, changed, excluded, failed, unconverted) to see what search can trust before relying on results or absence.

Instructions

Ask what the index could see before trusting a search or calling absence. Inventory of the root and what the index did with each file: indexed (in the index, matches disk), changed (differs from the index), excluded (an ignore rule or a type the index does not read; reason says which), failed (read or conversion error), unconverted (a PDF whose text layer the index could not read, or an office file with no extracted .md beside it; reason says which). A PDF is indexed from its own text layer, one section per page, unless a .md sits beside it — that sidecar is indexed instead, and both rows carry source_state: stale means the original changed after the conversion, unverifiable that the sidecar records no hash of it or its original is not under the root. index.state is cold when nothing was ever indexed: an empty listing there is not "no files".

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMax entries per page
cursorNo`next_cursor` from the previous page
folderNoRoot-relative folder to list; empty = the whole root
statusNoOnly this status: indexed, changed, excluded, failed, unconverted

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.11.0

TDQS

A4.3/5.0
Behavior5/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose4/5

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.

Usage Guidelines4/5

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.

Deploy Server

Other Tools