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

Annotations only say readOnly=false and idempotent=false, but the description adds meaningful context: on-device embedding, auto-creation with partition_by='scope', persistence, and the precise reason it is not idempotent (fresh ids per call). No contradiction with annotations.

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 primary action is front-loaded, and each subsequent clause adds operational value: required versus optional parameters, failure modes, and non-idempotency. Though dense, there is no filler or redundant restatement of the schema.

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?

Covers invocation requirements, parameter semantics, error conditions, and the non-idempotent behavior that would otherwise surprise an agent. The lack of an output schema is not a material gap for an insertion tool whose selection and invocation criteria are fully described.

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 fully compensates by explaining collection and texts as required, ids as auto-generated and conflict-prone, and metadata as per-text objects with scope routing. It also clarifies the one-per-text relationship between array parameters, which the bare schema cannot convey.

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?

Opens with 'Add text documents to a Telys memory collection', giving a direct verb and resource, and explains the outcome (embedded, inserted, persisted). It explicitly contrasts with telys_upsert for replacement, so an agent can distinguish add from sibling tools without opening other definitions.

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 'Use to store new memories' and gives a concrete alternative: 'use telys_upsert to replace' when an id already exists. It also lists failure conditions (empty texts, length mismatch, duplicate ids), which helps an agent avoid invalid calls.

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?

Beyond the annotations, the description discloses failure behavior (fails on missing collection), the optional faiss dependency with the exact fix command, and the threshold behavior (partitions below min_rows stay exact). Idempotent and non-destructive hints already cover safety, so this extra context adds real value.

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 dense but organized: purpose first, then when-to-run, then parameters, then failure and dependency notes. Every sentence earns its place; only minor redundancy exists because 'small partitions already use exact scans' and 'partitions below this stay exact' repeat the same idea.

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 build tool with no output schema, the description covers what it does, when to run it, all three parameters, a failure mode, and a dependency install path. It doesn't describe the return value, but that is less critical for an index-build command, and annotation hints already cover safety.

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 carry parameter meaning. It does: min_rows is given a default and below-threshold behavior, target_recall is tied to the recall floor, and collection is marked required. It could add value ranges or type constraints, but the core semantics are present.

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-object pair, 'Build per-partition IVF indexes,' and adds a concrete outcome ('calibrate nprobe to a recall floor'). It also scopes the tool to large partitions and notes exact scans for small partitions, which distinguishes it from sibling index tools like telys_build_lexical.

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 trigger: 'Run once a partition grows large,' and an explicit exclusion threshold through min_rows with partitions below staying exact. It doesn't name alternative tools such as telys_build_lexical or telys_tune, but the when-to-run guidance is unambiguous.

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?

The description adds behavioral detail beyond annotations: it discloses the failure condition when the collection doesn't exist, and notes the persistence of the index. It does not contradict annotations and aligns with idempotentHint and destructiveHint. It could mention behavior when lexical=False, but it's implied by the prerequisite.

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 concise, front-loads the main action, and organizes preconditions, parameters, and failure behavior in a logical order. Every sentence adds value.

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 build tool with three parameters and no output schema, the description covers the core context: purpose, sequencing, prerequisites, and parameter meaning. It doesn't detail the effect on an existing index or the exact failure mode for lexical=False, but these are minor given the annotations.

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?

Despite 0% schema description coverage, the description explains the purpose of k1 (term-frequency saturation) and b (document-length normalization) and their defaults, which the schema does not provide. This adds meaningful semantics beyond the raw type definitions.

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 states the action (fitting a BM25 lexical index), the resource (collection's retained tokens), and the outcome (persist). It also names the prerequisite and sequencing, distinguishing it from other build tools like telys_build_ivf by the 'BM25 lexical' specificity.

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 run (after bulk ingestion, before telys_search_lexical) and the required condition (collection created with lexical=True). This gives clear operational guidance without needing to inspect other 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?

Annotations already provide idempotentHint=true and destructiveHint=true, and the description adds value by explaining what is destroyed (tombstones and merged delta segments, not live data) and confirming 'the store is persisted.' It also details the no-op repeat behavior and the missing-collection failure, going beyond the annotation flags.

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 action statement is front-loaded, followed by usage timing, idempotency, and failure behavior. Every sentence carries distinct information with no filler, though the density slightly reduces skimmability.

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 single-parameter tool with no output schema, the description covers what, when, idempotency, side effects, and failure mode. An agent has everything needed to invoke it correctly; only minor details like prerequisites beyond collection existence are omitted.

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?

With 0% schema description coverage, the description must compensate, and it only partially does: 'Required: collection' restates the schema's required field, and 'Fails when the collection does not exist' implies collection is the target name. It does not elaborate on format, naming rules, or acceptable values, leaving meaning mostly inferable.

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 specific verbs and resources: 'flush tombstones' and 'merge the delta segment into the base layout' to reclaim space. This clearly distinguishes a storage-maintenance operation from its siblings (search, add, delete, stats), so an agent can tell them apart without opening 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?

Gives an explicit trigger condition: 'Use after large delete or update batches.' It also states the no-op behavior on repeat and the failure mode for missing collections. It does not name sibling alternatives or exclusions, but the context is clear enough to route correct usage.

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=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond that: the count is 'post-tombstone' (live rows) and it 'Fails when the collection does not exist or when `where` carries more than one key.' These are concrete behavioral traits not present in the annotations.

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 sentences, no fluff. The purpose is front-loaded, usage guidance follows, and parameter/error details are compact. Every sentence earns its place and there is no redundancy.

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 count tool, the description covers purpose, usage, parameter constraints, and failure modes. It doesn't explicitly state the return type/format, but 'Return the live row count' strongly implies a numeric value, and the lack of output schema is reasonable given the tool's simplicity. It is complete enough for an agent to invoke 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?

The schema already documents 'where' as 'optional single-key equality filter' with maxProperties=1. The description adds 'one key only' and failure conditions but does not clarify what 'collection' means or its expected format. With schema description coverage at 50%, the description only partially compensates for the undocumented 'collection' 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?

The description states a specific verb and resource: 'Return the live row count (post-tombstone) for a collection, optionally where-scoped.' It also distinguishes itself from sibling tools by explicitly positioning this as a 'cheap size check without pulling the full id list,' which differentiates it from telys_ids and telys_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?

The description gives clear context for when to use the tool: 'Use for a cheap size check without pulling the full id list.' This implies when not to use it, but it does not explicitly name the alternative tool or state exclusions, so it lacks the direct 'use X instead' guidance that would earn a 5.

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?

Discloses key behavior beyond annotations: the collection is built but NOT persisted until a mutating tool writes to it, telys_list_collections won't show it until then, and repeated calls with the same name return the existing collection unchanged. These details align with and enrich the idempotentHint annotation.

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 dense but every sentence earns its place: purpose, alternative usage, parameter semantics, persistence caveat, and idempotent repeat behavior are all covered. It front-loads the core action and follows with the most important caveats, with 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?

Given the minimal schema and absence of an output schema, the description is remarkably complete: it covers what the tool creates, how to use it, parameter details, persistence behavior, listing visibility, and idempotence. An agent has enough to invoke it correctly and predict its side effects.

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%, so the description fully carries parameter explanation. It states name is required, defines partition_by as a single metadata key name, gives its default 'scope', and warns that compound keys must be composed into one string — meaningful guidance beyond the bare 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?

States a specific action — create a named Telys memory collection in the active store — and distinguishes it from telys_add, which auto-creates on first write. It also clarifies that the collection is wired to the built-in embedder, making the tool's role unmistakable among the 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?

Explicitly says the tool is optional because telys_add auto-creates, and tells the agent when to prefer this tool: when you need to fix the name and partition key up front. This gives clear decision guidance versus siblings and covers the non-persistence consequence.

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 destructiveHint=true and idempotentHint=true, and the description adds meaningful detail beyond those flags: deletion is a tombstone rather than immediate physical removal, space is reclaimed later by telys_compact, repeated deletion is a no-op, and deletion fails for a nonexistent collection. This is exactly the kind of behavioral context that helps an agent predict side effects.

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?

Every sentence earns its place: core semantics, deferred reclamation, use case, required parameters, idempotency, and error condition. The description is concise and front-loaded with the most important behavioral fact.

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

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

For a destructive, idempotent tool with two parameters and no output schema, the description covers what gets deleted, when to use it, repeat behavior, failure mode, and the relationship to compaction. An agent can safely infer how to invoke it and what to expect.

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 carries the burden of explaining parameters. The description adds 'external id' semantics to ids, marks both collection and ids as required, and notes that collection must exist. It does not describe collection's meaning at length, but for two simple parameters this is sufficient.

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

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

The description opens with a specific verb and resource: 'Tombstone rows by external id', and states the observable effect ('no longer appear in queries or id listings'). It also distinguishes this tool from telys_compact by clarifying that space is reclaimed later by that sibling, so an agent can separate deletion from physical compaction.

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 'Use to forget memories' gives a clear intended use case, and the description states required inputs and failure condition. It does not explicitly list when-not-to-use or alternatives, but since there is no other delete tool among the siblings, no alternative routing is necessary.

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 mark the tool read-only and idempotent, and the description adds meaningful behavioral detail: unknown ids return found:false rather than an error, failures occur only for missing collections, and repo-indexed rows trigger a re-read from disk. This goes well beyond the annotations.

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 behavior and then efficiently covers edge cases, defaults, and failure semantics. Every clause adds operational value; there is no repetition of obvious schema facts or 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?

Given the lack of an output schema, the description supplies the essential contract: per-id results, found flag, metadata, optional source text, and failure behavior. It also mentions the disk re-read path, which is important operational context for repo-indexed rows.

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 low (25%), but the description compensates by naming required parameters, noting defaults, and explaining with_text's repo-index behavior. It also connects 'ids' to external ids and with_metadata to stored metadata, though the exact effect of with_metadata=false remains somewhat implied.

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 precise operation ('Exact row lookup by external id'), names the return concept ('found flag plus stored metadata'), and explicitly contrasts itself with similarity search. It also references the repo-search hit workflow, making its role distinct among many siblings.

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 use cases: 'Use to fetch known rows or read the code behind a telys_repo_search hit.' It also states a clear exclusion ('no similarity search') and clarifies error behavior, so an agent can decide when this tool is appropriate.

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?

Beyond the readOnlyHint and destructiveHint annotations, the description adds behavioral detail: tombstoned entries are excluded ('live (non-tombstoned)'), and it discloses two failure modes (collection missing, where with more than one key). This adds useful context without contradicting annotations.

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 three dense sentences: purpose, use case, and requirements/failure conditions. Every sentence earns its place, with no redundant filler, and the core action is 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?

For a simple two-parameter read-only enumeration tool with no output schema, the description covers purpose, usage, requirements, and failure modes. It could mention the return format (e.g., array of ids) or any pagination, but the stated purpose and annotations make the behavior clear enough 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 only 50% ('where' has a description, 'collection' does not). The description compensates by explicitly stating collection is required, giving an example for where (scope=project:acme), and reiterating the one-key constraint. This adds meaning beyond the bare schema fields.

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 'Return the live (non-tombstoned) external ids in a collection', which is a specific verb+resource statement. It further clarifies the tool's role as 'enumerate what is stored before a bulk update or delete', distinguishing it from search, get, and count siblings without needing to name 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 explicitly states a concrete use case: 'Use to enumerate what is stored before a bulk update or delete.' It also provides parameter requirements and failure conditions, but does not explicitly compare to alternatives like telys_search or telys_get, so it stops short of full 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?

Goes well beyond annotations: discloses .gitignore handling, common build/dep dir skipping, binary/symlink refusal, incremental fingerprinting with re-embedding and tombstones, fast no-op when nothing changed, force rebuild, and exact failure conditions. Annotations are all consistent with this 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?

Dense but efficient: core behavior is front-loaded, followed by incremental semantics, then parameter defaults, then failure modes. Every sentence adds information, though the single long paragraph could be lightly structured with separators.

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, state-mutating indexing tool with nine optional parameters and no output schema, the description covers scope, edge cases, failure conditions, and idempotent behavior. Nothing an agent needs to invoke it safely 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?

With only 22% schema coverage, the description carries the burden and largely succeeds: it lists all nine parameters with defaults, explains mode values, gives the '0 = unlimited' convention, and defines force. It lacks detail on the exact semantics of max_file_bytes/max_files, but the names plus defaults give enough orientation.

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?

Description opens with a specific multi-step action: walk a repo directory, chunk text files, and ingest chunks into a collection for telys_repo_search. This clearly distinguishes it from read/search siblings like telys_repo_search and telys_search, and from single-document tools like telys_add/telys_upsert.

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 makes the purpose explicit (preparing a repo for telys_repo_search) and gives context-dependent behavior (git checkout vs non-git, skip dirs, refusals). It does not explicitly name alternative tools to use instead, but the sibling separation is clear enough that an agent can infer when indexing is needed.

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, and non-destructive behavior. The description adds valuable non-obvious behavior: empty stores return an empty list rather than an error, and collections never written to by a mutating tool are omitted. It also discloses the environment-variable path resolution and sorted output, which are not in the schema.

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 action and resource, and every subsequent sentence adds meaningful behavioral or contextual detail. It is long enough to be complete 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 simple, parameterless, read-only list tool with no output schema, this description fully covers the path, return shape, empty-store behavior, and a likely pitfall (missing collections due to no prior writes). An agent has everything needed to call it and interpret the result.

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

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

With zero parameters, schema coverage is complete and there is little to add. The description still reinforces that the tool takes no arguments, which removes any ambiguity for an agent deciding whether it needs to supply inputs.

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 a specific verb ('List'), a precise resource ('Telys memory collections'), and the active store location via $TELYS_MEMORY_PATH. It also states the output is sorted names)Skip the behavior is distinct from siblings like search or stats.

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 searching or writing, giving clear context for when it is appropriate. It does not directly name alternative tools or exclusion conditions, but for a zero-argument discovery tool the guidance is sufficiently clear.

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?

Explicitly discloses that the tool re-runs incremental indexing on every call, writes to the store (contradicting any read-only assumption), and mentions performance ('cheap on no-change'). This goes well beyond the annotations (readOnlyHint:false, idempotentHint:true) and provides valuable 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 front-loaded with the core purpose, then moves to usage, parameters, failure modes, and a side-effect note. Every sentence adds value with no redundancy, making it concise yet comprehensive.

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?

Despite lacking an output schema, the description covers the tool's behavior, side effects, failure modes, prerequisites, and parameter usage. It provides enough context for an agent to call the tool correctly and understand the consequences, including that it is not read-only.

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 must compensate. It explains path_hint ('exact repo-relative path to scope the search'), top_k (default 5), and notes query is required. While query semantics are not elaborated beyond being required, the description covers all parameters adequately for a search tool.

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+method: 'Search the auto-indexed repo collection with the on-device embedder.' It clearly defines the tool's scope and distinguishes it from generic search (telys_search) by focusing on the auto-indexed repo collection and its re-indexing behavior.

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?

Provides a clear use case ('map this codebase and search it' workflows), required/optional parameters, failure conditions, and setup instructions. It doesn't explicitly name sibling alternatives like telys_search, but the context is sufficient for an agent to know when to use this tool.

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, and non-destructive, and the description adds valuable behavioral detail beyond them: the server embeds the query on-device, results come from 'live rows', and the tool returns isError for missing collections or multi-key `where` filters. This gives the agent concrete expectations about execution and failure.

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 dense but every sentence earns its place: purpose and mechanics, intended usage, required/optional parameters with example, and failure modes. The most decision-relevant information is front-loaded before parameter details, with no filler or repetition of the schema.

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?

Despite having no output schema, the description covers return shape (hits with id, score, metadata), required and optional parameters, a filter example, and error behavior. For a read-only search tool with supporting sibling tools, nothing essential is missing for an agent to select and invoke it 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 only 25%, but the description compensates thoroughly: it explains that `query` gets embedded, that `top_k` defaults to 5, and that `where` is a single-key equality filter with a concrete example (scope=project:acme). It also flags required vs optional parameters and the failure condition tied to `where`, making every parameter actionable.

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

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

The description opens with a specific verb and resource: 'Semantic + lexical search over a Telys memory collection.' It then explains the execution model (embedding `query` and returning best-matching hits) and names the return fields (id, score, metadata), making it clearly distinguishable from siblings like telys_search_lexical and telys_repo_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?

The description gives a clear use context: 'Use to recall stored notes/facts/decisions before answering.' It also provides an exclusion path by stating the tool fails when the collection does not exist and directing the agent to write first via telys_add or telys_create_collection. It stops short of explicitly contrasting with telys_search_lexical, so it earns a 4 rather than a 5.

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 establish read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context beyond that: the dependency on collection creation with lexical=True, the need for telys_build_lexical to have run, and the exact failure modes when the collection or index is missing. This meaningfully fills gaps that annotations do not cover.

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: the core behavior and key differentiator appear first, followed by prerequisites, parameters, and failure conditions. Every sentence earns its place; there is no filler or redundancy with the schema.

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 search tool with five parameters and no output schema, the description covers the essential operational context: purpose, prerequisites, failure modes, and parameter semantics. It does not describe the return shape or pagination, but for a keyword search this is a modest gap given the annotations already convey safety.

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 20%, so the description carries the load. It explains the required collection and query, assigns meanings to optional top_k and explain (including 'per-hit score explanations'), and reinforces the where parameter's single-key equality filter. It adds useful semantic detail beyond the bare schema, though it does not describe value formats or constraints for collection/query.

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: on-device BM25 lexical search. It explicitly contrasts with fuzzy semantic search, and the detail about exact-term matching for identifiers and rare tokens helps distinguish it from the sibling telys_search. It also names the required prerequisites, making the tool's role 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?

The description gives clear context on when to use lexical search (exact-term matching where semantic search is fuzzy) and lists the hard prerequisites (lexical=True and telys_build_lexical must have run). It does not explicitly name the alternative sibling telys_search, but the semantic-vs-lexical contrast provides sufficient usage 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, and non-destructive behavior; the description adds valuable beyond-annotation detail by stating that the tool fails when the collection does not exist and that runtime-provided counters vary by runtime version. This gives an agent useful expectations about behavior and 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 two sentences with no filler. It front-loads the core purpose, then efficiently covers usage, required inputs, and failure behavior. Every clause 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?

For a simple one-parameter, read-only tool with no output schema, the description covers what it does, what it returns, when to use it, and failure behavior. The only missing element is explicit sibling differentiation, but the stated purpose and output fields are enough for correct selection and 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 the bare 'collection' string parameter. It does clarify that collection names a Telys memory collection, is required, and that a missing collection causes failure. It could add format examples or valid sources, but for a single self-descriptive parameter this is adequate.

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

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

The description opens with a specific verb and resource: 'Report stats for one Telys memory collection', then enumerates the returned fields (name, partition key name, live external-id count, runtime counters). This makes the tool's scope clear and distinguishes it from siblings like telys_list_collections and telys_count.

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 the tool 'to confirm a collection exists and gauge its size', giving a clear context for invocation. It does not name exclusions or alternative tools when not to use it, so it stops short of a 5.

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?

The description discloses key behavioral traits beyond the annotations: it may apply changes, dry_run true never applies, false always applies, omitting follows the tuner default, and the call fails if the collection does not exist. It does not detail what applying a plan changes or whether it is reversible, but the provided semantics are materially useful.

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 three tight sentences with no filler. The primary purpose is front-loaded, followed by required/optional parameters and failure behavior. Every sentence contributes actionable 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 tool with no output schema and no positive annotations, the description covers required input, optional behavior, failure condition, and intended use case. It does not describe the TuningPlan return shape, but the core decision to call and how to call it is sufficiently supported.

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% because collection has no description, but the tool description compensates by marking collection as required and defining the full dry_run semantics. This gives the agent enough parameter-level understanding without opening 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?

The description states a specific action: 'Produce a TuningPlan for a collection via its Tuner' and clarifies it is for inspecting or applying index/maintenance recommendations. This distinguishes it clearly from the sibling search, add, and collection-management tools. It is not a tautology and names a concrete resource and operation.

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 gives explicit guidance on when to use the tool: 'Use to inspect or apply index/maintenance recommendations.' It also explains the dry_run behavior with three clear modes. However, it does not explicitly contrast with similar-looking siblings like telys_build_ivf, telys_build_lexical, or telys_compact, so it leaves some selection reasoning to the agent.

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=false, idempotentHint=true, and destructiveHint=false; the description adds value beyond these by disclosing concrete failure modes not in the annotations: missing/null ids fail with an exact error message, failures on nonexistent collections, ids/texts length mismatch, and the defaulting of the partition key when metadata is omitted. No contradiction with annotations.

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 its purpose and each subsequent sentence earns its place: usage context, required-parameter contract, sibling alternative, optional metadata semantics, and failure conditions. It is dense rather than padded, though slightly long; the parenthetical alternative guidance could arguably be folded in.

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 mutation tool with no output schema and 0% schema coverage, the description covers the essentials: what it does, when to use it, parameter relationships, and all documented failure modes. The only gap is the absence of any statement about the return value on success, which is minor given the otherwise thorough treatment.

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 carries the full explanatory burden and largely succeeds: it labels collection/texts/ids as required, clarifies texts are re-embedded, insists ids must be existing, and specifies metadata is one object per text with partition-key defaulting. This meaningfully exceeds the bare schema types; only minor details like text formatting or id-matching semantics are absent.

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 pairing: 'Replace the vectors/metadata of EXISTING ids by re-embedding new texts, then persist.' It clearly states the operation is for correction of known rows and explicitly differentiates from telys_upsert, whose insert-or-replace semantics are the inverse of this tool's require-existing-ids behavior.

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 gives explicit usage direction: 'Use for deliberate corrections to known rows' and names the alternative explicitly — 'use telys_upsert to insert-or-replace instead.' It also spells out the contract condition (ids must exist) that routes an agent to the alternative tool, leaving no ambiguity about when to pick this over a sibling.

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?

The description goes beyond the idempotentHint annotation by detailing that existing ids are 're-embedded and replaced as a versioned update (never a duplicate physical row)' and that the collection is auto-created. It also discloses the failure condition on length mismatch. While it doesn't cover every conceivable side effect, it meaningfully supplements the annotations without contradicting them.

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 dense but well-organized, with a clear core behavior statement followed by usage context and explicit required/optional sections. Every sentence adds value, though the length is slightly more than minimal due to the detailed idempotency and fallback explanations.

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 5-parameter mutation tool with no output schema, the description covers required/optional semantics, error conditions, and fallback behavior. It doesn't specify the return value, but that's not essential for invocation. Overall, it gives enough context for an agent to call it 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 description coverage is 0%, so the description fully compensates. It explains the role of each parameter: collection, texts, ids (required), metadata as 'one object per text', partition_by with default 'scope' and auto-creation, and the special behavior of JSON null ids. It also clarifies the length-matching constraint between ids and texts.

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 states the tool does 'add-or-replace text rows by external id' and differentiates new vs. existing ids, explicitly calling it the 'idempotent write path'. It also distinguishes itself from telys_add by noting that explicit JSON null ids fall back to telys_add with generated ids, so the purpose is unambiguous and distinct from siblings.

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?

Provides explicit when-to-use guidance: 'Use when the caller owns the ids and a repeated call must converge instead of conflicting'. It also explains the fallback to telys_add when ids are omitted, and notes the collection is auto-created when absent, giving the agent clear decision 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the null-workspace behavior, which is valuable context beyond the annotations. It does not mention potential performance or network dependencies, but for a simple config report, the added null handling is sufficient. No contradiction.

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 two sentences, front-loaded with the purpose and exact output fields. The usage guidance and null-handling note are integrated without fluff. Every sentence adds value.

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 zero parameters and no output schema, the description fully specifies what the agent will receive (path, repo_id, collection name, file count, cache persistence) and how to interpret the null case. Nothing critical is missing for an agent to call this 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?

The tool takes zero parameters, so the schema is trivially 100% covered. The description reiterates 'Takes no arguments,' which is redundant but harmless. Baseline 4 applies because there are no parameters to document.

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 ('Report') and a clear resource (the server's configured workspace), and enumerates exactly what is reported (path, repo_id, collection name, file count, cache persistence). It clearly distinguishes this as an informational tool, different from the search, mutation, and collection management siblings.

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 instructs when to use the tool: 'Use to verify which repo telys_repo_search will index before calling it.' It also clarifies the null workspace case ('that is a report, not an error'), which guides the agent on interpreting results. No alternative is needed since this is a unique read-only inspection tool.

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