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

The description goes far beyond the annotations by disclosing non‑idempotency ('NOT idempotent... a repeat call inserts additional new rows'), failure conditions, auto-creation behavior, and the routing role of the `scope` field. It also specifies that texts are embedded on-device and persisted. No contradiction with annotations; idempotentHint=false aligns with the explicit claim.

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: the core action is front-loaded, required/optional parameters are clearly separated, and key behavioral warnings (non-idempotency, failure conditions) are explicitly called out. The length is justified by the tool's complexity, and there is no redundant phrasing.

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

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

For a tool with no output schema and four parameters, the description fully covers what an agent needs to invoke it correctly: required and optional inputs, failure modes, auto-creation behavior, and the relationship to the upsert alternative. Nothing critical 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%, but the description adds substantial semantic value: it explains positional correspondence for ids and metadata, auto-generation when ids are omitted, conflict behavior for existing ids, and the use of `scope` for partition routing and later where-filtering. This goes well beyond the schema's basic type descriptions.

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 ('Add text documents') and a clear resource ('Telys memory collection'), and explains the operation's mechanics (embedded on-device, inserted as row, persisted). It distinguishes itself from siblings by explicitly scoping its role to storing new memories and by pointing to telys_upsert for replacement, so an agent can tell them apart.

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 clearly when to use it ('Use to store new memories') and gives an explicit alternative condition ('an id that already exists raises a conflict, so use telys_upsert to replace'). It also covers failure cases (empty texts, length mismatch, duplicate ids) and notes auto-creation of the collection, which removes the need for telys_create_collection in this flow.

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?

Adds meaningful behavior beyond the annotations: the tool mutates indexes, fails when the collection does not exist, and requires the optional faiss dependency with remediation commands. The idempotentHint and destructiveHint annotations are consistent with the description, and the dependency behavior is valuable extra 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 compact and well-structured: purpose first, sibling differentiation second, parameter guidance third, and failure/dependency notes last. Every sentence adds value and none are redundant.

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 prerequisites, defaults, failure mode, and dependency installation, which is substantial for a maintenance tool with no output schema. It does not describe what the tool returns on success, but the core invocation context is complete enough 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 coverage is 100%, so the baseline is 3. The description mostly restates the schema defaults and behavior for min_rows and target_recall, while adding only that the required collection must exist. This is adequate but does not significantly deepen parameter understanding 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?

States a specific verb and resource: 'Build per-partition IVF indexes and calibrate nprobe to a recall floor' for approximate search. It also distinguishes itself from sibling maintenance tools by naming telys_compact and telys_tune with their differing purposes.

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 clear usage context: use for partitions that have outgrown exact scans, and identifies it as a maintenance sibling of telys_compact and telys_tune. It does not provide explicit 'use X instead' exclusion rules, but the context is specific enough to route an 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 establish the safety profile (write, idempotent, non-destructive), and the description adds consistent behavioral context beyond them: the index is persisted, the build requires an existing lexical collection, and it 'Fails when the collection does not exist.' No contradiction with annotations — it supplements them with workflow state 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?

Four purposeful sentences: action+precondition, sibling differentiation, workflow ordering, and parameter/failure summary. Nothing is wasted, though the parameter recap partially duplicates the schema; it remains tight and front-loaded with the core action.

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 reasonably omits return values, and it fully covers prerequisites, workflow ordering, parameters, and failure mode. The only gap is behavior when the index already exists, but the idempotentHint=true annotation covers re-invocation 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 coverage is 100%, so the schema already documents collection, k1, and b with defaults and semantic descriptions. The description restates k1 as 'term-frequency saturation' and b as 'document-length normalization,' mirroring the schema rather than adding new meaning, 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 opens with a concrete verb-resource pair — 'Fit the BM25 lexical index over the collection's retained tokens and persist it' — clearly stating what the tool does. It explicitly contrasts with telys_build_ivf, making the distinction from its closest sibling 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?

It names the direct alternative (telys_build_ivf builds the IVF vector index) and states the exact operational window: 'Run after bulk ingestion and before telys_search_lexical.' The precondition that the collection 'must have been created with lexical=True' further pinpoints when the tool is valid, leaving no inference 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, destructiveHint=true, and idempotentHint=true, and the description enriches them with the exact mechanics (tombstone flush, delta merge into base), a persistence guarantee ('the store is persisted'), idempotency behavior ('Repeating with no pending changes is a no-op'), and the failure mode. 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 compact, with each clause earning its place: core operation, when to use, alternatives, required parameter, idempotency behavior, and failure condition. The primary action is front-loaded 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 single-parameter, no-output-schema maintenance tool with rich annotations, the description covers operation, trigger condition, alternatives, persistence, no-op behavior, and error semantics. 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 schema already documents the single `collection` parameter, setting the baseline at 3. The description adds a small amount — the 'Required' reminder (redundant with the schema's required field) and the failure condition ('Fails when the collection does not exist') — which gives error expectations but doesn't substantially extend what the schema already provides.

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 specific verbs and resources ('Flush tombstones and merge the delta segment into the base layout, physically reclaiming space from deleted/updated rows'), precisely identifying the operation and its effect. It also distinguishes itself from siblings by naming telys_delete and telys_tune as alternatives, so an agent can differentiate 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'), names alternatives with their distinct purposes ('telys_delete to remove rows, telys_tune for index tuning'), and states the no-op case for repeated calls. This fully routes an agent's decision between this tool and its siblings.

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, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: 'post-tombstone' semantics, 'cardinality only' (no stats), the failure on nonexistent collection, and the single-key equality filter constraint. It does not describe return format, but with no output schema and a simple cardinality result, the description is reasonably transparent.

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 purpose is in the first sentence, followed by sibling differentiation, then parameter semantics and failure conditions. Every sentence earns its place; no filler or repetition of schema text.

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 read-only count tool with two parameters, full schema coverage, and strong annotations, the description is nearly complete. It covers purpose, scope, siblings, prerequisites, and failure modes. The only minor gap is the lack of an explicit return value description (e.g., integer count), but the phrase 'row count' and 'cardinality only' make the return obvious enough.

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 schema already documents both parameters. The description adds meaning by explaining the 'where' constraint in plain language ('single-key equality filter', 'more than one key fails') and by clarifying that 'collection' must be an existing collection in the active store. This goes slightly beyond the schema's own descriptions, so a 4 is appropriate.

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

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

The description states a specific verb ('Return the live row count'), a precise resource ('a collection'), and a scope qualifier ('post-tombstone', 'cardinality only, optionally where-scoped'). It also explicitly distinguishes itself from siblings telys_stats and telys_ids, so an agent can tell it 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?

The description explicitly names sibling alternatives (telys_stats for aggregate stats, telys_ids for enumerating ids) and gives clear when-to-use guidance. It also states prerequisites ('write first via telys_add or telys_create_collection') and failure conditions ('fails when it does not exist', 'more than one key fails'), 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?

The description discloses a key behavioral detail not in annotations: 'The new collection is built but NOT persisted, so telys_list_collections shows it only after a mutating tool (telys_add, telys_upsert, …) writes to it.' This is crucial for an agent to understand the actual state after the call. It also reinforces idempotentHint by stating repeating returns the existing collection unchanged, adding value beyond the 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 compact but covers multiple essential points: purpose, optional nature, parameter specifics, persistence behavior, and idempotency. It is front-loaded with the core purpose and does not waste words. A slight reduction could be made by trimming the persistence explanation, but it is valuable enough to justify the length.

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 2-parameter tool with no output schema, the description covers everything an agent needs: the action, the optionality, the parameters, the non-persistence caveat, and the idempotent behavior. It also implicitly distinguishes from siblings by explaining when to use it. No critical information 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 schema already documents both parameters. The description adds extra meaning: it clarifies that partition_by is a single metadata key name and instructs how to handle compound keys ('compose compound keys into one string yourself'). It also restates the default ('scope'). This is genuinely helpful beyond the schema, though the schema already provides the basics.

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 verb and resource: 'Create a named Telys memory collection in the active store, wired to the built-in embedder.' It distinguishes this from sibling tools like telys_add and telys_upsert by emphasizing that it's optional and for fixing the name and partition key up front. This is specific and 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 explicitly says 'Optional — telys_add auto-creates on first write — but use it to fix the name and partition key up front.' This tells the agent exactly when to use this tool vs. relying on auto-creation, and why. It also notes that repeating with the same name returns the existing collection, which implies idempotent behavior.

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 (destructive, idempotent), the description explains the tombstone mechanism, persistence of the store, deferred physical reclamation by telys_compact, and failure mode for nonexistent collections. This adds significant behavioral context not present in structured fields.

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 with the core action and effect, followed by usage context and edge cases. Every sentence adds valuable information; there is no fluff or 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 two-parameter tool with full schema coverage, destructive/idempotent annotations, and no output schema, the description covers behavior, persistence, failure, and usage intent. An agent has everything needed to 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 description coverage is 100%, and the schema already documents 'ids' as 'external ids to tombstone' and 'collection' as 'name of an existing collection.' The description repeats the requirement ('Required: collection, ids') but adds no new 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?

The description uses a specific verb, 'tombstone,' and identifies exactly what is affected (rows by external id) and the observable consequence (no longer appear in queries or id listings). It also implicitly distinguishes this from telys_compact, which reclaims physical space, making the tool's role clear relative to 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?

The description gives a direct use case ('Use to forget memories') and important behavioral conditions (repeat is a no-op, fails if collection missing). It does not explicitly contrast with alternative deletion or modification tools, but there is no other obvious delete sibling and the stated context is sufficient for correct selection.

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 readOnly/idempotent annotations, the description discloses important behavior: unknown ids return found:false instead of error, failures only occur when the collection is missing, and repo-index rows trigger a disk re-read of the source slice. This adds meaningful 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 information-dense with no filler. The core exact-lookup purpose is front-loaded, and each subsequent clause adds distinct value: return shape, repo-row behavior, usage context, parameters, and error 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?

With no output schema, the description compensates by specifying the return shape (one entry per id, found flag, metadata), the unknown-id behavior, and the only failure condition. It is complete for an agent to select and 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?

Schema coverage is 100%, so the schema already documents all parameters and defaults. The description repeats required/optional status and the with_text re-read behavior, adding little beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Exact row lookup by external id' and explicitly contrasts with 'no similarity search.' It also names the related sibling telys_repo_search, making the tool's role clear.

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 when to use the tool: 'Use to fetch known rows or read the code behind a telys_repo_search hit.' It also signals when not to use it by stating 'no similarity search,' which distinguishes it from search siblings.

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 this as read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: no pagination, full id list in a single response, unspecified internal row order, client-side sorting advice, and explicit failure conditions for missing collections or multi-key where filters.

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 efficient: purpose, sibling differentiation, parameter guidance, result shape, ordering caveat, and failure modes are all covered in a compact, front-loaded structure. No sentence is wasted.

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

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

For a two-parameter read-only enumeration tool with no output schema, the description covers everything an agent needs: what is returned, pagination behavior, ordering semantics, and failure conditions. The safety profile is already carried by annotations, and the description fills the remaining operational gaps.

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 schema already documents both parameters. The description restates the single-key equality constraint and gives an example, but it does not add significant meaning beyond what the schema's maxProperties and descriptions already provide.

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: 'Return the live (non-tombstoned) external ids in a collection.' It also distinguishes itself from siblings by explicitly stating this is 'enumeration without ranking,' which separates it clearly from telys_search 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?

The description names the relevant siblings and their behaviors: 'telys_search returns ranked hits with scores for a query; telys_count returns just the cardinality.' This gives an agent explicit context for choosing this tool over alternatives, and the required/optional parameter breakdown reinforces when it applies.

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 idempotentHint annotation, the description discloses concrete behaviors: fingerprinting by size/mtime, re-embedding only changed files, tombstoning removed files, a fast no-op path, .gitignore and build-dir handling, and refusal of binaries or escaping symlinks. It also states failure conditions, giving the agent a clear model of 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?

The description is long but every sentence earns its place: main behavior, incremental semantics, routing, return values, parameters, and failure cases. Information is front-loaded with the core purpose and the parameter summary is compact.

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 9-parameter tool with no output schema, the description covers defaults, modes, limits, return shape, collection behavior, failure conditions, and relationship to sibling tools. Nothing essential is missing 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 coverage is 100%, and every parameter already has a clear description plus defaults. The description mostly restates defaults and the '0 = unlimited' convention, adding organizational value but little semantic detail 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?

The description states a specific workflow: walk a repo directory, chunk text files, and ingest them into a collection for telys_repo_search. It clearly distinguishes itself from related siblings like telys_add/telys_upsert and telys_repo_search, so an agent can tell what this tool is for 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?

The 'Routing' sentence explicitly tells the agent when to use this tool versus alternatives: telys_repo_search queries the index, telys_add/telys_upsert store manual memories, and this tool indexes repo content. It also explains that re-calls are incremental, making repeated invocation safe.

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?

The description adds significant behavior beyond the annotations: it discloses that every call re-runs telys_index_repo, that hits are always fresh, that each hit includes a source slice re-read from disk, and explicitly warns that the re-index writes to the store so the tool is not read-only. This is exactly the kind of side-effect disclosure that helps an agent call safely, and it aligns with readOnlyHint=false and idempotentHint=true.

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: main action, freshness behavior, use-case guidance, requirements, failure modes, and side-effect warning. The information is dense but well-ordered, with the core purpose front-loaded before caveats.

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 tool's complexity and that no output schema exists, the description covers the essentials an agent needs: parameters, defaults, prerequisites, failure behavior, side effects, and a rough sense of the return payload ('each hit carries the exact source slice re-read from disk'). Nothing critical for correct invocation 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 description coverage is 100%, so the schema already documents query, top_k, and path_hint. The description restates these in prose ('Required: query. Optional: top_k (default 5) and path_hint') and adds the operational context of on-device embedding, but it does not materially extend the parameter meaning beyond what the schema already provides.

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: 'Search the auto-indexed repo collection (default 'repo_symbols') with the on-device embedder.' It also distinguishes itself from siblings by centering on repo-automated collection search and naming telys_index_repo as part of its operation, so an agent can separate it from telys_search or telys_search_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 clearly scopes usage to 'map this codebase and search it' workflows and gives prerequisites and failure modes. It does not explicitly name alternatives to avoid, but the workflow context plus the 'repo collection' framing is strong enough that an agent understands when this tool, rather than a generic search 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds valuable behavioral context beyond annotations: failure when the collection doesn't exist, the single-key restriction on 'where', and the on-device embedding behavior. It does not contradict any 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 detailed but well-structured: it opens with the core purpose, then usage guidance, then parameter specifics, and closes with error conditions. Every sentence adds value; it is not padded with filler. Slightly long but appropriate for the tool's complexity.

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

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

For a tool with 4 parameters, a nested object, and no output schema, the description covers return format (hits with id, score, metadata), required vs optional, filtering constraints, error scenarios, and usage context. An agent has enough to call it correctly without additional documentation.

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 baseline is 3. The description adds meaningful context beyond the schema: the 'where' filter example ('scope=project:acme'), the note that MCP-created collections are partitioned by 'scope', and the default for top_k. It doesn't fully compensate for the lack of output schema, but it enhances parameter understanding.

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 a specific verb ('search') and resource ('Telys memory collection'), explains the embedding mechanism, and explicitly differentiates from telys_search_lexical. It leaves no ambiguity about what the tool does.

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

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

It provides explicit when-to-use guidance ('recall stored notes/facts/decisions before answering') and contrasts with the lexical alternative ('choose this embedding-ranked path when wording varies; choose telys_search_lexical when exact terms and BM25 scoring matter'). It also notes required vs optional parameters and error conditions.

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 meaningful extra behavioral context: the tool fails if the collection doesn't exist or the lexical index was never built, and explain adds per-hit score explanations. 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 dense and front-loaded, leading with the core behavior and sibling distinction. It loses a point for slight redundancy: 'otherwise the call fails' and the final 'Fails when...' sentence restate the same failure concept.

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

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

For a five-parameter search tool with no output schema, this description covers the essential guidance: what the tool does, when to use it, required preconditions, all parameters, and explicit failure modes. An agent has enough information to invoke it correctly and avoid common mistakes.

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

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

Schema coverage is 100%, so the schema already documents all five parameters. The description adds value by tying the collection parameter to the telys_build_lexical prerequisite and clarifying that query is for BM25 exact-term matching, but most parameter details are already in 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 names the exact operation: on-device BM25 lexical keyword search with exact-term matching. It explicitly distinguishes this from the sibling telys_search, which handles vector/embedding retrieval, so an agent can tell them apart without opening either 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 explicitly identifies when to use this tool versus the alternative: exact-term matching for identifiers and rare tokens versus fuzzy semantic search. It also states the required precondition that the collection must have lexical=True and telys_build_lexical must have run, plus the failure conditions when those are not met.

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 readOnly, idempotent, and non-destructive behavior lebensraum. The description adds meaningful behavioral context beyond those annotations: the operation fails when the collection does not exist, and the runtime-provided counters vary by runtime version. This gives an agent useful expectations about variability and failure without contradicting the annotation profile.

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 with no filler. The core purpose and output contents are front-loaded, followed by routing guidance and then the requirement/failure caveat. Every sentence earns its place, making the description compact yet information-dense.

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 read-only stats tool with no output schema, this description is complete enough. It explains what stats are returned, mentions version-dependent counters, states the practical use case, distinguishes siblings, and includes the failure mode. An agent has the information needed to select and invoke this tool 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 100%, and the input schema already documents 'collection' as the name of an existing collection. The description reinforces this by saying 'Required: collection' and noting the failure condition, but it adds little truly new semantic information about the parameter's format, possible values, or behavior. Baseline 3 is appropriate because the schema carries the full parameter documentation.

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 action ('Report stats') and resource ('one Telys memory collection'), then enumerates the output contents: name, partition key name, and live external-id count. It explicitly contrasts itself with telys_list_collections and telys_count, making its purpose unambiguous and distinguishable 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?

It explicitly states when to use this tool: to confirm a collection exists and gauge its size. It also names alternatives and explains their narrower scope, with telys_list_collections enumerating collections and telys_count returning cardinality only. The required parameter and failure condition when the collection does not exist further guide invocation.

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 annotations, the description discloses critical behavioral traits: dry_run controls apply vs. plan-only, applying sets default recall and crossover, IVF-builds oversized partitions, skips already-built ones, requires faiss, runs live in-process without disk persistence, and is non-atomic with possible partial application on failure. No contradiction with annotations exists.

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, sibling distinction, side effects, failure behavior, verification, and parameter requirements. It is front-loaded with the core purpose and structured so an agent can act on it immediately.

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 success and failure modes, mutation semantics, non-atomicity, compute implications, and how to verify results. An agent has enough context to invoke the tool correctly and anticipate consequences.

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. The description repeats that collection is required and dry_run is optional, adding no new meaning about the parameters beyond what the schema already provides.

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: 'Produce a TuningPlan for a collection via its Tuner, and optionally apply it.' It also explicitly differentiates itself from telys_build_ivf, 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?

It states the tool is for inspecting or applying index/maintenance recommendations, names the sibling telys_build_ivf as the direct-build alternative, and directs the agent to verify the after-state with telys_stats. This gives clear when-to-use and when-not-to-use 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=false, idempotentHint=true, and destructiveHint=false meaning mutation is expected, and the description adds contract-level behavioral detail: strict null id rejection with error message, persistence, and failure modes. It does not fully describe all side effects, but with annotations covering the safety profile the added detail is valuable.

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: main action, use case, required parameters, strict contract, and failure conditions all appear in four sentences. It is perhaps slightly redundant with schema text but each sentence earns its place and the core behavior 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 write operation with no output schema, the description covers essential invocation context: required params, optional metadata behavior, persistence, and failure conditions. It would benefit from stating the return value or success response, but given the rich schema and annotations, the remaining gap is minor.

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% and every parameter is already documented with clear descriptions (e.g., 'one per id', 'strict: required', 'partition key is defaulted when omitted'). The description mostly echoes these details, adding only the strict error message and usage clarification. Baseline 3 is appropriate because the schema carries the parameter burden.

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 operation: replace vectors/metadata of EXISTING ids by re-embedding new texts, then persist. It differentiates from the sibling telys_upsert ('insert-or-replace instead') and uses precise scope ('existing ids', 'deliberate corrections to known rows').

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 an explicit when-to-use signal ('Use for deliberate corrections to known rows'), explicitly names the alternative for insert-or-replace (telys_upsert), and documents failure conditions (missing/null ids, collection not existing, length mismatch). This fully routes an agent to the correct 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 convey idempotentHint=true and readOnlyHint=false, and the description adds valuable specifics: versioned updates, never duplicate physical rows, auto-creation of collections, and failure on length mismatch. These go beyond the annotations and inform the agent of important side effects and constraints.

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 each sentence carries critical information: core behavior, usage context, required/optional parameters, and a failure condition. It is front-loaded with the primary purpose and does not waste words, though it is somewhat lengthy for a tool description.

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 write operation with 5 parameters and no output schema, the description covers all essential aspects: upsert semantics, auto-creation, null handling, length mismatch failure, and default partition. It doesn't describe return values, but for a write path that's less critical, and the failure condition is disclosed. The description is sufficiently complete 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 coverage is 100% (all properties described), so the baseline is 3. The description adds extra semantics: the null-handling for ids (treated as omitted = telys_add), positional mapping for metadata, and the default partition_by 'scope' with auto-creation. This enriches the parameter understanding 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?

The description clearly states the action 'Add-or-replace text rows by external id' and explains the behavior for new vs existing ids, distinguishing it from siblings like telys_add and telys_update. It names the specific resource and verb, making the tool's purpose 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?

Explicitly states when to use: 'Use when the caller owns the ids and a repeated call must converge instead of conflicting — this is the idempotent write path.' It also contrasts with telys_add by explaining that explicit JSON null for ids reverts to plain telys_add with generated ids, providing clear alternative 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=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.