kontexta

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

With no annotations, the description fully discloses behavior: additive, idempotent per tag, auto-creates rows, persists to local SQLite, no external auth/rate limits, returns success object, throws on unknown file_id. This goes far beyond what structured data provides.

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. Front-loaded purpose, then behavior, then usage alternatives. No filler, perfectly sized.

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 no output schema, the description explains return value and error behavior. It also covers persistence, auth, and rate limits. Fully complete for a tag-add operation.

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 covers both params but with terse descriptions. The tool description adds meaningful behavior for tags (auto-create rows, idempotent) and file_id (throws if unknown), enhancing 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 ('Append tags to ONE file'), the resource ('file'), and the additive nature. It also explicitly distinguishes from siblings like tag_search_results and remove_tags.

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 label a single file' and provides direct alternatives: 'To tag every file matching a query in one call use `tag_search_results`; to remove tags use `remove_tags`.' This is exemplary 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?

With no annotations, the description carries full burden and does so excellently. It discloses read-only status, no side effects/auth/rate limits, the rank-order budget behavior, skipped[] remainder, and filter semantics (project_id null = KB only, tags require ALL). This goes far beyond minimal requirements.

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, then adds behavior and usage. Three sentences with no filler; every clause earns its place. It balances completeness with brevity.

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 6 parameters, no output schema, and no annotations, the description fully explains what happens (capped by max_tokens, skipped[] remainder), when to use it, and all important filter semantics. It is sufficient for an agent to select and invoke the tool correctly without needing more context.

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 value by explicitly stating defaults (format=xml, max_tokens=50000) and clarifying combined filter semantics (project_id null = KB only, tags require ALL). This synthesizes schema details into actionable context, though it largely restates schema info, so not a 5.

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 (FTS search + concatenate into a bundle) and specifies the exact output formats (XML or markdown). It explicitly positions itself against siblings by saying 'Use instead of search + N×read_file when you need several related files as one context blob', distinguishing it from similar 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?

The description gives explicit when-to-use guidance: 'Use instead of search + N×read_file when you need several related files as one context blob.' It also implies when not to use it (for individual files) and sets expectations about budget behavior. This clearly directs the agent to choose this tool over alternatives.

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

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

With no annotations provided, the description carries full burden and excels: it flags 'SIDE-EFFECTFUL', 'NOT idempotent / no de-dup', auth defaults, upstream throttling, AUTH_REQUIRED error details, and return format. This is comprehensive behavioral disclosure.

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: side-effect warning, process, idempotency, auth, rate limits, errors, return, usage. Dense but well-organized and front-loaded with the most critical warning.

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 (external fetch, auth, error handling) and no output schema, the description is complete: it explains return values, error codes, and operational caveats. No significant gaps 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 for parameters is 100%, so baseline is 3. The description adds meaningful value beyond the schema by giving concrete examples for `headers` (Cookie, Authorization) and tying them to the auth flow, enhancing agent 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 explicitly states the tool 'fetches an EXTERNAL URL and writes a NEW KB file' and details the full pipeline (download, Readability extraction, markdown conversion, save). This distinguishes it from sibling file-creation tools by focusing on external ingestion.

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 clear context ('Use to ingest external docs into the KB') and explains when to pass headers for authenticated pages, but does not explicitly name alternative tools or state when NOT to use it. This is clear guidance without exclusions.

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

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

With no annotations provided, the description fully discloses behavioral traits: network access, reliance on local git credentials, idempotency with skipped commits, error conditions (no backup repo, push failure), and return value structure. This is exemplary transparency.

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 contributes critical information about side effects, auth, idempotency, error behavior, and return values. No filler 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?

Given the tool's complexity (network, git, auth, errors, return value) and absence of an output schema, the description covers all essential aspects: what happens, what is returned, when it throws, and when to invoke it. It is fully self-sufficient.

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 only parameter is project_id, whose schema description is minimal ('Project ID'). The description adds context by referring to 'the project's KB data,' implying what the ID is used for. Since schema coverage is 100%, this is adequate but not enhanced beyond baseline.

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's purpose: syncing KB data to a git backup directory, creating a commit, and pushing to origin. It uses specific verbs and resources, and it is easily distinguished from siblings like file management or journal 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?

The description explicitly states when to use the tool: 'Use after a batch of KB writes to get changes off-machine.' It does not mention alternatives or exclusions, but the guidance is clear enough to place it above the baseline.

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

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

With no annotations provided, the description fully carries the burden of behavioral disclosure. It explicitly states the side effect can be 'highly destructive (running arbitrary shell commands, modifying files, etc.)', that the token itself is the auth (no external auth, no rate limits), and that invalid tokens return an inert text response, not an error. This provides complete transparency.

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 and well-structured. It front-loads the purpose, then provides critical usage and behavioral details in a logical order. Every sentence serves a purpose without redundancy or fluff.

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 simplicity (1 required parameter, no output schema), the description covers all necessary aspects: purpose, usage context, behavioral implications, and parameter semantics. It is complete and self-contained, leaving no ambiguity for an AI agent.

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

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

The description adds significant meaning beyond the schema. While the schema simply says 'The approval token from the pending response', the description elaborates that the token is returned by any confirm-required Hands tool, expires in 60 seconds, cannot be reused, and serves as the authentication mechanism. This provides essential context for correct usage.

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's action: 'Approve and EXECUTE a previously-issued Hands invocation by its single-use approval token.' It uses a specific verb (Approve and EXECUTE) and resource (Hands invocation), and distinguishes itself from siblings by referencing a unique single-use token mechanism.

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 the tool: 'only call when the user has authorised the pending action.' It also warns against misuse by stating the token expires in 60 seconds and cannot be reused. However, it does not explicitly list alternative tools or when not to use it, which would elevate the score to 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?

With no annotations, the description fully bears the burden of behavioral disclosure and excels. It reveals that the operation writes to disk, indexes in SQLite FTS5, auto-creates missing directories, returns metadata (ID, path, estimated tokens), and explicitly states no external auth or rate limits apply. This is far beyond typical descriptions.

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

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

The description is a single dense paragraph that front-loads the core purpose in the first sentence. It includes some repetition of schema details (e.g., tags/folder optional), but every sentence serves a purpose and the structure is logical, moving from action to behavior to usage to parameters.

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 7 parameters, 3 required, and no output schema, the description is remarkably complete. It covers purpose, usage, behavioral side effects, parameter constraints, return metadata, and an alternative tool. Nothing critical is missing for an agent to select and invoke the 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 coverage is 100%, so baseline is 3, but the description adds meaningful semantics: it interprets the 'destination' enum values (global KB, project repo, internal schema file), clarifies that 'project_id' is strictly required for project/kontexta, and explains the 'format' default and its mapping to '.mmd'. This exceeds the schema's bare 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+resource ('Create a new markdown or mermaid file') and immediately specifies the valid destinations (knowledge, project, kontexta). It also explicitly distinguishes itself from 'update_file', making its scope 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?

The description states when to use the tool ('Use this tool to instantiate new contextual documents or notes') and provides an explicit alternative ('To modify an existing file, use 'update_file' instead'). It also details destination-specific requirements (project_id required for project/kontexta), giving clear contextual 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?

With no annotations, the description fully covers behavioral traits: side effects (writes to disk, FTS5 inserts, mkdir), partial success semantics (`errors[]`, `error_count`), return structure, and absence of auth/rate limits. This is exceptionally 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 a single, well-structured paragraph that front-loads purpose, then covers constraints, behavior, and return values. Every sentence adds value without 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?

Given the tool's complexity (batch creation with partial success, multiple parameters, no output schema), the description covers all necessary context: how to use, what to expect, error handling, and return format. No gaps remain.

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 meaning by explaining the `format` parameter (.md vs .mmd), the conditional requirement of `project_id`, and the batch limit of 200. This goes beyond the schema's minimal 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 clearly identifies the tool as a batch variant of `create_file`, specifies it creates up to 200 markdown or mermaid files, and mentions the key constraint of batch size. This distinguishes it from the sibling `create_file` and other 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?

The description advises 'Use for bulk ingestion' and for '>200 items, page yourself', implying when to use. It also notes the `project_id` requirement for certain destinations. However, it does not explicitly state when to prefer the singular `create_file` instead, which is a minor gap.

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

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

With no annotations, the description carries the full burden and delivers: idempotency, rejection criteria (empty names, null bytes, leading separators, '..'), side effects (disk mkdir, no DB rows until file lands), and no external auth/rate limits. This is exceptionally transparent about behavior and consequences.

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 appropriately sized, front-loading the primary purpose in the first sentence. Every subsequent sentence adds crucial operational details (idempotency, rejections, side effects, return value) without redundancy or fluff.

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 no output schema, the description discloses the return shape ({path, base_path}) and covers edge cases, side effects, and constraints. It is complete enough for an agent to invoke confidently 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 coverage is 100%, so baseline is 3. The description adds value by clarifying nested path behavior ('notes/inbox' creates intermediates), which enriches the 'name' parameter beyond its schema description. It also implies project_id semantics ('project root vs KB'), adding contextual meaning.

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 'Create a folder under a project root or the KB', with a specific verb (create) and resource (folder), and distinguishes it from siblings like create_file and delete_folder. The mention of idempotency and nested path handling further clarifies scope.

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 clear context for when to use the tool (under a project root or KB, with nested path support) but does not explicitly contrast with alternatives like create_files. The idempotent behavior and rejection cases implicitly guide usage, though no explicit 'use this instead of X' statement exists.

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

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

With no annotations, the description fully discloses behavior: it is destructive and permanent, differentiates between KB files (unlinked from disk and removed from FTS5 index) and project reference files (only index entry removed), notes non-idempotence (throws on unknown ID), states no auth/rate limits, and specifies the return 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?

Starts with 'DESTRUCTIVE.' as a clear warning, then packs essential behavioral details, error semantics, return value, usage guidance, and alternatives into a tight paragraph. Every sentence adds value without 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?

Despite no annotations and no output schema, the description covers the tool's purpose, behavior, edge cases (unknown ID), return value, safety guidance, and related tools. It is complete for a destructive single-file deletion operation.

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 covers the only parameter 'id' with description 'File ID' (100% coverage). The description doesn't add meaning beyond that, though it contextualizes how the ID affects behavior (KB vs project reference). This meets the baseline for full schema coverage.

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

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

The description uses a specific verb and resource: 'Permanently delete one file by ID.' It clearly distinguishes this tool from the bulk variant 'delete_files' and from alternatives like 'remove_tags' and 'set_favorite'.

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 only when the file is truly obsolete.' It provides clear alternatives: 'to deprioritise without losing data, untag (remove_tags) or unfavorite (set_favorite) instead.' Also mentions the bulk variant for multiple files.

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

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

With no annotations, the description carries full transparency burden. It discloses physical deletion rules (KB unlinked vs project de-indexed), per-ID error isolation, partial success, non-idempotency, and lack of auth/rate limits. This exceeds typical transparency.

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 provides unique value: scope, deletion rules, error behavior, idempotency, auth, and preview guidance. The opening line front-loads the critical 'DESTRUCTIVE batch' warning.

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 simple single-parameter schema and no output schema, the description fully covers operation semantics, return format, error handling, and alternatives. There are no unanswered questions for an agent deciding to invoke it.

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% (the `ids` array is described as 'File IDs to delete (max 500 per call)'). The description adds behavioral meaning: unknown IDs become per-item errors, failures don't abort the batch, and returns a structured result. This enhances 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?

The description opens with 'DESTRUCTIVE batch — delete up to 500 files by ID in one call', clearly stating the verb, resource, and batch scope. It distinguishes itself from the singular `delete_file` sibling by emphasizing the batch nature and the 500-file limit.

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 references `delete_file` for shared deletion rules and advises running `list_files` to preview before deleting, providing a concrete alternative. While it doesn't state 'use delete_file for a single file', the batch distinction is clear from the name and description.

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

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

With no annotations provided, the description carries full burden and delivers: labels itself DESTRUCTIVE, explains recursive deletion of disk and FTS rows, states the project_id refusal and its rationale, warns about non-recoverability except git backup, notes no external auth/rate limits, and states the return value. This is comprehensive and directly addresses the tool's safety 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?

The description is four sentences, front-loaded with 'DESTRUCTIVE' and then covers key aspects: scope, refusal behavior, validation, recoverability, auth/rate limits, and return value. Every sentence carries essential information with 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?

Given the tool's destructive nature, lack of annotations, and no output schema, the description is remarkably complete. It explains what gets deleted, the race condition caveat, alternative action, recovery options, external constraints, and the success response format. This leaves the agent well-prepared to invoke the tool correctly and understand 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 coverage is 100% for both parameters, so the baseline is 3. The description adds marginal value by referencing 'Same name validation as create_folder' for the name parameter, but the project_id semantics are already fully described in the schema. It does not significantly deepen 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 uses a specific verb (delete) with a clear resource (folder under the KB) and scope (recursively, including every file inside, disk + FTS rows). It distinguishes from sibling tools like delete_file and delete_files by specifying folder-level recursive deletion, and clearly states the refusal behavior for project_id.

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 provides explicit when-not-to-use guidance: it refuses project_id deletions and tells the user to remove project content via their editor instead. It also references create_folder for name validation, giving context for expected behavior. However, it does not explicitly frame this as an alternative to delete_file or delete_files, though the folder-vs-file distinction is implicit.

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

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

With no annotations, the description carries the burden of disclosing behavior. It adds useful context: 'no token cost', 'Operates locally with no auth or rate limits', and implies a read-only operation via 'Return'. It does not explicitly state 'does not modify the file', but the described behavior strongly implies non-destructive, which is adequate.

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 moderately sized, front-loaded with the core purpose, and each sentence contributes value (purpose, return fields, operational details, usage guidance, parameter note). It is slightly long but not bloated, and the structure flows logically from what to when to parameter.

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 low complexity (one parameter, no output schema), the description covers the essential aspects: what the tool returns, when to use it, operational constraints, and parameter validation. It does not describe the exact return format, but the list of fields provides sufficient context for a metadata retrieval tool.

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

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

Schema coverage is 100% with one required 'id' parameter described as 'File ID'. The description adds 'id' must be a valid integer file ID, which slightly clarifies the required format but is largely redundant with the schema's type declaration. This is a baseline score as the schema already documents the 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 clearly states the tool's purpose: returning metadata about a file without pulling its content. It lists specific fields ('Tags, size, est_tokens...') and explicitly contrasts with read_file, making it distinct from 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?

The description provides explicit guidance on when to use this tool: 'Use this when you'd otherwise chain read_file + list_tags + get_history + find_related just to decide whether to actually read the file.' It names alternatives and the exact scenario, making it highly actionable.

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

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses that it is a static document, does not read any project file or DB row, is read-only with no side effects, auth, or rate limits, and takes no parameters. This fully preempts any behavioral concerns.

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 well-structured and every sentence adds value: what it returns, its static/read-only nature, no parameters, usage context, and sibling alternatives. It is appropriately sized for the tool's simplicity and front-loads the key purpose before the guidance.

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 has no parameters, no output schema, and zero annotations, the description is complete. It covers the tool's content, behavior, limitations, and usage context, leaving no obvious gaps for an AI agent to be confused about selection or 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?

The tool takes zero parameters and the schema confirms this with an empty properties object. The description explicitly states 'Takes no parameters', which is consistent with the schema. Per rubric, a zero-parameter tool gets a baseline of 4, and the description reinforces that.

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 returns the complete authoring reference for `kontexta.json`, including schema, validation rules, and an annotated example. It explicitly distinguishes itself from siblings by naming `list_hands` for viewing loaded tools and `reload_hands` for applying edits, making its unique 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?

The description gives explicit when-to-use guidance: 'Use when helping a user write or fix a `kontexta.json`'. It also names the exact alternatives (`list_hands` and `reload_hands`) and what they are for, providing clear exclusions and alternative routing.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses the tool is read-only with no side effects, auth, or rate limits, and details the possible statuses and return contents on divergence, including what is NOT returned.

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 and front-loaded with the core purpose. Every sentence adds value: purpose, statuses/return details, contrast with get_diff, read-only note, and usage guidance. No wasted words.

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 tool with one parameter, no output schema, and no annotations, the description is complete. It covers purpose, behavior, return values, statuses, usage context, and the follow-up action, leaving no significant 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% (file_id is described as 'File ID'). The description does not add parameter-specific semantics beyond the schema, but the baseline of 3 is appropriate given the high coverage and single simple 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 clearly states the tool's purpose: 'Diagnose drift between one file's disk content and its FTS index.' It uses a specific verb and resource, and explicitly distinguishes itself from sibling tools like `get_diff` (full diffs) and `refresh_index` (fix).

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 provides explicit when-to-use guidance: 'Use when search results look stale; if status is `diverged` or `no_index_row`, run `refresh_index` to fix.' It also contrasts with `get_diff` to clarify when not to use it.

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

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

With no annotations provided, the description carries the full burden. It clearly describes the pipeline's side effects (writing markdown entries and advancing high-water) and explicitly states it is idempotent, which is valuable behavioral context. It does not cover every edge (e.g., permissions or errors), but core behaviors are 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 a single, dense sentence that conveys the full pipeline in a clear, front-loaded manner. Every clause adds meaning, with no redundant or vague wording.

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?

The description gives a good overview of the pipeline and idempotency, but with no output schema, annotations, or parameter explanations, it misses return-value details and how the parameters influence behavior. It is adequate for a basic understanding but incomplete for full operational use.

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% for two parameters (max_events and project_slug), and the description does not explain either parameter. It mentions 'raw events since high-water mark' and 'group by topic' but does not connect these to the input parameters, so it fails to compensate for the schema's lack of 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 clearly states the tool's function with a specific verb ('Run the distillation pipeline') and details each step: reading raw events since high-water mark, grouping by topic, writing mechanical markdown entries, and advancing high-water. This distinguishes it from sibling tools like journal_append or distill_journal_commit_upgrades.

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 implies the usage context: run when there are raw events since the high-water mark needing distillation. However, it does not explicitly state when not to use it or mention alternative tools, so guidance is only implicit.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly discloses the side effect: 'Updates journal_meta.status_latest to mark the entries as upgraded.' It does not mention error handling, idempotency, or reversibility, but for a simple status update the core behavior is 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?

Two sentences that are front-loaded and dense: first sentence gives the trigger, second gives the effect. No filler, no repetition of the tool name or 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 single-parameter tool with no output schema, the description covers the purpose, the trigger, and the effect. It does not explain what 'mechanical journal entries' are or how to obtain the task slugs, but these are covered by sibling tools and domain context. A small gap is the lack of any mention of validation or response behavior.

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 provides a clear description for the only parameter (task_slugs: 'Task slugs whose entries were upgraded by subagents.'), so baseline is 3. The tool description adds minor workflow context ('affected task slugs') but no new syntax or format details 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 verb and resource: 'Updates journal_meta.status_latest to mark the entries as upgraded.' It also gives workflow context ('After dispatching subagents to upgrade mechanical journal entries') that distinguishes this from sibling tools like distill_journal, which likely performs the upgrade itself.

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 clearly indicates when to use the tool: 'After dispatching subagents to upgrade... call this with the affected task slugs.' This establishes a prerequisite and sequencing. It does not explicitly name alternatives, but the 'after' clause makes the intended usage 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?

With no annotations provided, the description carries the full burden and does so thoroughly: it states 'Read-only; no side effects, auth, or rate limits', details the return format ('annotated file rows with shared_tag_count and shared_tags'), and explains empty-result semantics. This exceeds the minimum disclosure expected.

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 sentences, front-loaded with the main purpose, then safety/return details, then empty-result guidance and alternatives. Every sentence earns its place with no redundancy 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?

For a simple two-parameter tool with no output schema, the description covers purpose, ranking logic, side-effect-free operation, return fields, empty behavior, and alternative tools. It provides a complete picture for an agent to select and invoke the 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 coverage is 100%—both `file_id` and `limit` have descriptions in the schema. The description only restates the default limit and adds no extra meaning beyond what the schema already provides, 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 uses a specific verb ('Find') and clearly identifies the resource ('other files sharing tags with the given file') and the ranking criterion ('by shared_tag_count descending'). It distinguishes itself from content-based search tools by focusing on tag-based relationships.

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 addresses the empty-result case, pointing to search/regex_search for content-based discovery and suggest_tags for bootstrapping labels. This gives the agent clear guidance on when to use this tool versus alternatives in a common scenario.

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

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

With no annotations provided, the description carries full burden and excels: it states read-only, no side effects, auth, or rate limits; explains that order matters and reversing args inverts the diff; and discloses the error condition (throws if hash unknown). This is comprehensive behavioral disclosure.

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, each packed with useful information: the core action, safety/behavioral traits, and usage guidance. No wasted words, and the most important information (what it does) comes first.

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 no output schema and no annotations, the description covers all necessary context: the return type (unified diff), prerequisites (hashes from get_history), error behavior (throws on unknown hashes), and side-effect profile (read-only). It is complete for a function of this complexity.

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 has 100% coverage with basic descriptions, but the tool description adds crucial semantics: it emphasizes that commit_a is the earlier side and that reversing args inverts the diff. This goes beyond the schema by explaining the consequence of parameter order, which is essential for correct use.

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 ('Return'), the resource ('the unified diff of one file'), and the scope ('between two commit hashes'), distinguishing it from siblings like get_history (which shows that changed, not what) and diff_against_disk (which compares working tree). It 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 to use it after get_history and explains the benefit ('see WHAT changed, not just THAT it changed'). It also implies when not to use it (when you only need the history) and indicates the hashes typically come from get_history, providing clear context relative to alternatives.

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

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

With no annotations provided, the description fully carries behavioral disclosure. It states the tool is read-only, has no side effects, auth, or rate limits; explains which repo is read based on file ownership; and clarifies the meaning of an empty result. This goes well beyond the structured 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?

Four sentences, each earning its place: the first states purpose and output, the second describes repo behavior and side-effect profile, the third defines the return contract and empty-array meaning, and the fourth gives usage guidance. It is tight, well-organized, and front-loaded with the most important 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 single-parameter tool with no output schema, the description is exceptionally complete. It covers what the tool returns, the structure of the response, the edge case of an uncommitted file, read-only safety, and use cases. Nothing important 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?

The schema only says file_id is the 'ID of the file,' but the description adds semantic value by explaining that the tool reads the file's owning repo (project repo vs KB backup repo). This gives the agent a better mental model of what file_id can refer to. The high schema coverage earns a baseline of 3, and this added context lifts it to 4.

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 ('Return') and precise resource ('git commit history for one file'), including ordering ('newest first') and returned fields. It also distinguishes itself from sibling tools by explicitly mentioning get_diff and restore_file for related but different 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?

Provides clear when-to-use guidance: 'Use to understand a file's evolution before editing or restoring.' It also names alternatives ('Pair with get_diff to see exact line changes; use restore_file to roll back'), giving explicit context for choosing this tool vs 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?

With no annotations provided, the description takes full responsibility for behavioral disclosure. It states the tool is read-only with no side effects, auth, or rate limits, and specifies error behavior (invalid regex throws) and response shape. This is transparent and covers safety concerns.

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, front-loading the core action and constraints. Each sentence adds distinct value—scope, use cases, safety, errors, return format, and guidance—without 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 tool with no output schema, the description fully covers what the agent needs: what it does, its limitations (capped results), return structure, error behavior, and when to use it relative to siblings. It is complete 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 coverage is 100% with descriptions for all four parameters, so the baseline is 3. The description adds minimal extra parameter-specific meaning beyond the schema, though it does clarify the regex matching context ('catches what FTS misses') and the default/max caps, which relate to max_matches. Overall, no significant additional parameter insight is provided.

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's function—matching a JS regex against one file's lines and returning line numbers—and differentiates it from siblings like regex_search (cross-file) and search (keyword/concept). The mention of catching FTS misses adds specific use-case context.

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 guidance: use after read_file_outline when you know the file and need a specific reference. It also names alternatives for cross-file regex (regex_search) and keyword search (search), making the decision criteria 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?

With no annotations provided, the description carries the full burden. It explicitly discloses that the operation is 'idempotent' and names the concrete effects ('prunes old raw .jsonl files', 'archives cold tasks'), which informs the agent about the tool's side effects. It stops short of explaining reversibility or permission requirements, but the key behavioral traits are covered.

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 short, front-loaded sentences with no filler. The first sentence states the action, the second adds a safe-rerun guarantee, and the third details what gets pruned/archived. Every sentence 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?

Given the tool's modest complexity (one parameter, no output schema), the description is mostly complete: it states the action, the idempotency guarantee, and the high-level effects. It does not explain how the retention policy is configured or what the operation returns, but this is minor given the simple interface.

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

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

There is only one parameter, project_slug, and the schema just says it's a string with no description (0% coverage). The tool description mentions 'for a project' but never names or explains the project_slug parameter, its format, or whether it is required. The description fails to compensate for the schema's lack of detail.

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 verb ('Run') and resource ('journal retention/archival') and provides concrete details ('prunes old raw .jsonl files', 'archives cold tasks') that clearly distinguish it from sibling journal tools like journal_append and journal_status.

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 usage context is implied by the word 'retention/archival' and 'per the configured retention policy', but the description does not state when to use this tool versus alternatives, nor does it provide exclusions or preconditions. It is adequate but lacks explicit 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?

With no annotations, the description discloses file creation and same-day file_id behavior, which is useful. However, it does not specify safety aspects (e.g., whether it's read-only or destructive), rate limits, or authentication requirements, leaving gaps.

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 extremely concise: two sentences covering purpose, creation behavior, and return value. Every sentence adds value with no redundant or filler content.

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 low complexity (2 params, no output schema, no nested objects), the description fully covers what an agent needs: what the tool does, what it returns, and the idempotency behavior within a day. No missing critical details.

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 fully documents the parameters. The description adds minimal value beyond stating the purpose of appending text and optional project context; it does not provide format or constraints 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 (append timestamped text entry), the target (today's daily journal file), and key behaviors (creates file if missing, same file_id for same day). It effectively distinguishes from sibling tools like journal_note or distill_journal.

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 implies usage for appending to today's journal but provides no explicit guidance on when to use this tool versus alternatives (e.g., journal_note, journal_intent). No exclusion criteria or when-not-to-use context is given.

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

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It clarifies that the tool records a pivot and that distillation uses this record, but it does not mention any permissions, side effects, or return values. For a simple journaling action this is adequate, though not rich.

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 zero wasted words. It front-loads the action and resource, then immediately provides usage context and downstream rationale. Every sentence 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?

Given the tool's simplicity (one required parameter, no output schema, no nested objects), the description provides complete context: what it does, when to use it, and why it matters. There is no meaningful missing information for an agent 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 coverage is 100% and the single 'summary' parameter is already well described in the schema. The description adds no additional parameter meaning beyond what the schema provides, so the baseline score of 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 uses a specific verb ('Record') and a clear resource ('a topic/intent pivot'), and it distinguishes this tool from siblings like journal_append and journal_note by focusing on intent pivots. It immediately conveys what the tool does and when it is relevant.

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 states when to use the tool ('Use when the user redirects what you're working on') and explains the downstream effect on distillation. It does not provide explicit 'when not to use' guidance or name alternative tools, but the context is clear enough for most cases.

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

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

With no annotations provided, the description carries the full disclosure burden. It explains the persistence behavior (stored as an 'agent_note' event), the storage layer (Layer 1), and the downstream effect (surfaces in distilled task entries). This is meaningful and goes beyond a generic 'record a note' statement.

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 concise sentences, front-loaded with the core purpose, and every phrase adds relevant information. No filler 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?

Given the low parameter count and no output schema, the description provides sufficient context: what the tool does, where the note is stored, and how it surfaces later. It does not mention return values, but that is not essential here. The description is complete enough for an agent to select and call the 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?

The input schema already documents both parameters ('text' as body with markdown allowed, 'tags' as optional array). The description does not add significant parameter-specific semantics beyond those already present, so the baseline of 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 specific action verb ('Record') and a clearly scoped resource ('free-form decision/abandonment/observation note in the current project's journal'). It also differentiates the tool from siblings like journal_append by describing the storage mechanism ('agent_note event in Layer 1') and downstream effect ('surfaces in distilled task entries').

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 conveys when to use the tool: for decision, abandonment, or observation notes in the current project's journal. It does not explicitly list alternatives or exclusion scenarios, but the context is strong enough to guide appropriate 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?

With no annotations provided, the description must disclose behavioral traits. It only states the tool 'report's status, implying a read-only operation, but does not mention side effects, authentication needs, rate limits, or return format. This is insufficient for a tool without annotation support.

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

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

The description is a single, front-loaded sentence with no redundant information. Every word contributes to the purpose.

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 simplicity (one parameter, no output schema), the description provides the basic purpose. However, it does not explain what the 'report' output looks like or what statuses are available. For a reporting tool, this is a notable gap.

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 has 0% coverage on parameter descriptions, but the tool description does not add any meaning to the sole parameter 'project_slug'. It is left implicit what value it should take or how it is used. The description fails to compensate for the lack of schema 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 clearly states a specific action ('Report') on a specific resource ('journal backlog and high-water mark') for a project. This distinguishes it from sibling tools like 'journal_append' or 'distill_journal' which perform different actions.

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

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

No guidance is provided on when to use this tool versus alternatives such as 'distill_journal' or 'housekeep_journal'. The description lacks any context about appropriate use cases or exclusions.

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

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

With no annotations provided, the description carries the full burden and fully delivers: it declares read-only, no side effects, auth, or rate limits. It also discloses response characteristics (`total_est_tokens`, row fields) enabling the agent to plan token usage. No contradictory annotations exist.

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 well-structured and every sentence adds value: function, filters, safety declaration, response details, semantic nuance, and tool differentiation. No filler 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 tool with 7 optional parameters and no output schema, the description is remarkably complete. It explains the response shape, the purpose of `total_est_tokens`, and provides usage context, making it easy for the 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 description coverage is 100%, so the baseline is 3. The description lists the filter parameters and adds the key `project_id: null` clarification, but this is already present in the schema. It doesn't substantially elevate parameter 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 clearly states the tool lists file metadata with specific filters and pagination, using a specific verb and resource. It explicitly distinguishes itself from siblings by directing users to `search` for content lookup and `project_map` for a denser dump.

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 to browse known structure' and names alternatives (`search`, `project_map`). Also clarifies the nuanced `project_id: null` vs omit behavior, which is crucial for 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?

Even though no annotations are provided, the description fully discloses behavioral traits: 'Read-only; no side effects, auth, or rate limits' and 'Throws if project_id references an unknown project'. This covers safety, error handling, and permissions comprehensively.

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?

Five concise sentences, each serving a distinct purpose: core action, return shape, safety, error behavior, and usage guidance. No redundancy or filler; every sentence 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?

The description is fully self-contained for a 1-parameter tool with no output schema or annotations. It explains return format, relative path semantics, error behavior, and relationships to sibling tools, making external context unnecessary.

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 already documents project_id with 100% coverage ('Pass null or omit to list KB folders'). The description adds the error condition for unknown projects and clarifies the Knowledge Base context, providing extra value 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?

Description clearly states the action: 'List folder paths under a project root (or the Knowledge Base when project_id is null/omitted)'. It also distinguishes from create_folder by explicitly noting that to create a folder one should use create_folder.

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 use cases: discovering where to drop a new file via create_file's folder argument or navigating vault structure. It also names create_folder as the alternative for creation, guiding the agent on tool 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?

With no annotations provided, the description carries full burden. It explicitly states 'Read-only; no side effects, auth, or rate limits', and explains the data source (per-project kontexta.json files), providing complete behavioral disclosure.

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 yet information-dense: purpose, source, safety, usage guidance, and pointers to related tools are all included in three sentences with 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?

Despite no output schema, the description lists the fields returned and fully explains the tool's role, safety profile, and relationship to siblings. It is a complete and self-sufficient description.

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 has zero parameters and the schema is empty (100% coverage), so there are no params to document. Baseline 4 is appropriate; description adds no parameter-specific info but isn't needed.

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 explicitly states 'List every Hands command tool currently registered' with precise output fields (project scope, tool name, danger level, confirmation flag, description), and distinguishes itself from siblings like reload_hands and describe_hands_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 clearly explains when to use this tool ('discover what side-effectful project commands the agent is permitted to run') and points to alternatives: 'see describe_hands_schema' for schema and 'reload_hands' after editing.

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

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

No annotations provided, so the description carries full burden. It discloses 'Read-only; no side effects, auth, or rate limits' and explains the derived has_hands flag condition, exceeding minimal requirements.

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, front-loaded with the action and output, then usage and alternatives. Every sentence provides unique value with no redundancy or padding.

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 low complexity and absence of output schema/annotations, the description fully covers return fields, behavioral assurances, and usage context. It is complete for a simple list operation.

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 has zero parameters and the schema is empty (100% coverage vacuously). Per rubric, 0 parameters earns baseline 4; the description adds no parameter detail but none is needed.

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 'List every registered project' with specific output fields (id, name, absolute path, has_hands flag), making the action and resource unmistakable. It also distinguishes from siblings by explaining this tool provides the project_id for scoped tools and contrasting with register_project/list_hands.

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 tells when to use: 'Use to find the project_id to pass to scoped tools' and lists those tools. Also directs to register_project for registration and list_hands for Hands inspection, clearly covering alternatives.

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

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

With no annotations, the description carries the full transparency burden and fully delivers. It discloses read-only behavior, no side effects, no auth or rate limits, and the non-paginated nature of the response, all of which are meaningful operational traits.

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 sentences with no fluff. Purpose, safety, return behavior, and usage guidance are each addressed once and in a logical order, making the description easy to scan and act on.

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 covers everything an agent needs to select and invoke the tool: what it returns, how it behaves, and when to use it. It also connects to sibling tools like remove_tags and describe_file, completing the contextual picture.

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 has zero parameters, so the schema provides complete coverage and parameter semantics are inherently unnecessary. The description still adds value by detailing the return fields (id, name, applied count), partially compensating for the missing output 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 a specific verb ('List') and resource ('every tag in the global SQLite database') and states the returned fields (id, name, applied count). It also differentiates from siblings by explicitly pointing to describe_file for file-specific tags, making its scope unmistakable.

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 when-to-use guidance: discover existing labels before tagging and find tag IDs for remove_tags. It also names an alternative (describe_file) for a different use case, providing clear decision criteria.

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

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

With no annotations, the description carries the full burden. It states 'Operates locally with no auth or limits' and discloses cross-project rejection, which are key behavioral traits. However, it doesn't mention return values or error handling.

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 sentences, front-loaded with the action. It packs in constraints and operational details without fluff. The 'Parameters' section is slightly redundant but extends schema descriptions.

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 move operation, the description covers key constraints and local operation. However, it lacks details about return values, overwrite behavior, and error states, which would be helpful since no output schema exists.

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% for both parameters. The description adds the important constraint that new_path must resolve inside the owning project or global directory, which the schema doesn't specify. For file_id, it merely repeats 'valid file ID', adding little value.

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 'Move/rename a file.', clearly stating the verb and resource. This distinguishes it from sibling tools like update_file or delete_file. The mention of 'rename' clarifies the dual functionality.

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 constraints (absolute path, inside owning project, cross-project rejection) but doesn't explicitly state when to prefer this over alternatives. Usage is implied by the verb 'move' and the constraints.

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

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

With no annotations, the description carries the full burden. It discloses idempotency (fenced markers + version skip no-op writes), file modification (project configuration files), the mandatory user consent requirement, and the return structure. It does not mention if existing rules are overwritten, but the idempotency and versioning hint at safe behavior. This is good coverage for a mutating tool.

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

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

The description is well-structured: a one-sentence purpose, a mandatory consent warning, a concise parameter list with mode behavior, and a returns section. It is slightly longer than necessary due to repeating some parameter details that are also in the schema, but every section earns its place with the consent warning and mode logic being critical.

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, no annotations, and no output schema, the description covers all essential context: idempotency, consent, create/update mode behavior, parameter interactions, and the exact return format. It lacks error handling details (e.g., what happens if no context file exists and target_agent is omitted), but the description is sufficient for an agent to invoke the tool correctly in most scenarios.

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 context beyond the schema: it clarifies that files defaults to recommendation.target_files in update mode, that files is ignored when target_agent is provided (create mode), and specifies the exact condition for target_agent requirement. This adds practical meaning to the parameters, going beyond the schema 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 starts with 'Write or update the kontexta workflow rules block in a project's agent context file(s)' – a specific verb+resource that clearly distinguishes from generic file tools like update_file. It names the exact domain (kontexta workflow rules) and the target (agent context files), leaving 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?

The description provides clear context on when to use the tool: it explains create vs update modes, when files is ignored, when target_agent is required, and the mandatory consent step. However, it does not explicitly compare to sibling tools like update_file or create_file, so an agent may not know why to choose this over those alternatives. The guidance is strong but not fully explicit about alternatives.

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

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

With no annotations provided, the description carries the full burden, and it meets it thoroughly. It discloses read-only status, no side effects, no auth or rate limits, the `max_lines` cap, the `est_tokens` report, the warning-field behavior above `KONTEXTA_PROJECT_TOKEN_WARN`, and default values for flags. This is rich behavioral disclosure beyond what any structured field could infer.

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 yet information-dense—four sentences cover purpose, benefit, safety profile, output limits, parameter semantics, and usage guidance. It front-loads the core purpose and immediately conveys value with the token-saving comparison. No sentence is wasted; every clause adds useful 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?

This tool has no output schema and no annotations, so the description alone must convey what the tool returns and how it behaves. It does: it describes the output form ('compact indented outline'), the included fields, the token estimate/warning mechanism, and the parameter options. Combined with explicit usage guidance and alternatives, the description is complete for an agent to safely and correctly invoke the tool.

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

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

Although the input schema already covers 100% of parameters, the description adds meaning beyond the schema: it explains the null/omit distinction for `project_id` ('KB only' vs. 'everything') and states the defaults for `include_tags=true` and `show_titles=true`. This directly aids an agent in choosing correct parameter values, exceeding schema-level explanations.

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 a compact indented outline of folders, file titles, tags, and IDs in a single dense block.' It distinguishes itself from siblings by explicitly noting it uses substantially fewer tokens than the equivalent `list_files` JSON and by contrasting with `search` for keyword lookup. This makes the tool's unique purpose unmistakable.

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 when-to-use guidance: 'Use to orient yourself in an unfamiliar vault or project' and tells when not to use it: 'for keyword lookup use `search`.' It also clarifies nuanced selection behavior with `project_id: null` vs. omitted vs. a specific project, which serves as concrete 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?

With no annotations, the description discloses read-only nature, no side effects/auth/rate limits, return fields including est_tokens for context budgeting, and error behavior ('Throws if the ID is unknown').

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 focused sentences front-load purpose, then add return/error details and alternatives; no wasted words.

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 no output schema, it lists key return fields, error behavior, side-effect profile, and usage boundaries, which is sufficient for a single-parameter tool with rich sibling context.

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 covers the only parameter (id) at 100% with 'File ID'; description adds minimal semantic value beyond referencing 'by ID' and emphasizing a known file, meriting the baseline 3 for high schema coverage.

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 states 'Read one file's full body and metadata by ID' with a specific verb and resource, and explicitly distinguishes from siblings via 'Use for a single known file' and alternative tool mentions.

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 ('single known file'), and provides clear alternatives for inspection (describe_file), batch (read_files), partial (read_file_lines/read_section), and path-based (read_file_by_path) scenarios.

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?

Despite the absence of annotations, the description discloses the read-only nature with 'no side effects, auth, or rate limits', details the strict path-matching behavior ('no symlink resolution, no path normalisation beyond what the OS does, no trailing-slash tolerance'), and specifies failure semantics ('Returns isError if no row matches'). This fully compensates for missing 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?

Each of the four sentences serves a distinct purpose: defining the operation, specifying path constraints, stating error behavior, and giving usage guidance with alternatives. There's no redundancy 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?

For a simple single-parameter read tool with no output schema, the description covers its purpose, output shape (via reference to `read_file`), error handling, path requirements, and usage context. It also addresses the edge case of unindexed files. This is a complete and self-sufficient description.

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's `path` description only states it must be an absolute path matching storage. The tool description adds critical operational semantics: the path must match exactly as indexed, with no symlink resolution or normalization and no trailing-slash tolerance. This is a substantial enrichment over the schema, though it stops short of providing format specifications or examples.

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 tool's description opens with a clear action: 'Look up a file by its absolute on-disk path' and explicitly ties the output to `read_file`. It differentiates itself from the closely related `read_file` by emphasizing path-based lookup versus ID-based lookup and states a preference: 'if you have the ID, prefer read_file'. 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 gives explicit when-to-use guidance: 'Use when an agent has a path from its working directory but no file ID' and contrasts with `read_file` when an ID is available. It also suggests a fallback when the file is not found: 'try refresh_index'.

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

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

With no annotations provided, the description carries the full burden. It discloses read-only nature, no side effects/auth/rate limits, silent clamping for out-of-range bounds, throws on to<from, and return contents (snippet plus size_bytes and est_tokens). This is exemplary transparency for an unannotated tool.

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

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

Six sentences, each earning its place: core action, edge cases, side-effect declaration, return shape, use case, and sibling alternatives. Front-loaded with the primary verb and resource. No filler or repetition.

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 tool with 3 required params and no output schema, the description fully covers purpose, behavioral quirks, return values, and usage context. Nothing critical is missing; the tool is simple enough that this is complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description reiterates 1-indexed inclusive semantics and adds clamping behavior tied to from/to, but does not materially expand parameter meaning beyond the schema. No missed parameters or ambiguity.

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 starts with a specific verb+resource+scope: 'Return a 1-indexed inclusive line slice of a file.' It clearly distinguishes from siblings by naming exact alternatives (read_section, grep_in_file), making the tool's unique purpose unmistakable.

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 to inspect a stack-trace region or a chunk of a large file without pulling the whole body.' It also names alternatives with specific conditions: 'Prefer read_section if you know the heading, grep_in_file if you know a pattern but not the line number.' This is exactly what the rubric requires.

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

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

With no annotations provided, the description carries full burden and states 'Read-only; no side effects, auth, or rate limits.' It also discloses the empty-outline meaning and that content may still exist, which is important behavioral context for an agent deciding on next steps. This exceeds what schema or annotations would provide.

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, each earning its place: what is returned, read-only/usage guidance, and empty-case fallback. The purpose is front-loaded in the first sentence, and there is zero wasted 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?

The tool is simple (1 param, no output schema), but the description still covers return format (list of headings with fields), safety profile, usage context, and edge case (empty outline). It fully equips an agent to decide when to call this tool and what the result means.

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 describes file_id as 'File ID' with 100% coverage, so the baseline is 3. The description's mention of 'one file' aligns with the parameter but adds no new syntactic detail above the schema. Since the single parameter is self-explanatory, the baseline rating 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 begins with a specific verb 'Return' and clearly identifies the resource as 'a flat list of markdown headings for one file' including exact fields (level, text, line, byteStart, byteEnd). It distinguishes itself from sibling tools like read_file (full body), read_section (section reading), and update_file_section (section editing).

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 tells when to use: 'Use as a cheap probe before read_section or update_file_section' and provides a clear fallback: 'fall back to read_file or read_file_lines' when the outline is empty. This gives direct usage guidance and names alternatives.

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

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

With no annotations provided, the description carries full responsibility. It discloses the read-only nature, absence of side effects/auth/rate limits, the return structure (per-file records, total_est_tokens, errors[]), and the non-aborting error isolation. This is thorough and exceeds typical expectations.

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 concise sentences with no fluff. It front-loads the core purpose, then layers return details, safety, and usage guidance. Every sentence 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?

Given there is no output schema, the description explains the return values (per-file annotated records, total_est_tokens, errors[]) and error behavior. It also covers limitations and usage context, making it complete for a batch tool with a single parameter.

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?

Although the schema already describes `ids` as 'File IDs to read (max 200 per call)', the description adds meaningful context: the batching purpose, the aggregation of token estimates, and the paging strategy for >200 IDs. This goes beyond the schema's basic parameter description.

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

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

The description opens with a specific verb and resource: 'Batch read up to 200 files by ID in one call.' This clearly distinguishes it from the single-file sibling `read_file` and other file-reading tools. The scope and behavior are immediately evident.

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: 'Use instead of looping read_file to halve round-trips and get the combined token cost upfront.' It also provides a constraint: 'For >200 IDs, page yourself.' This gives clear actionable guidance on when and how to use it.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It states matching rules ('case-insensitive but exact-string after trim', 'fuzzy / partial matches do NOT resolve'), error behavior ('Returns isError if the heading is absent'), and safety ('Read-only; no side effects, auth, or rate limits').

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 (~80 words) and well-structured: it front-loads the core action and output, then clarifies matching semantics and error behavior, and ends with usage guidance. Every sentence adds value without 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?

The description covers purpose, output fields, error condition, matching edge cases, and provides alternative tool references. Given the lack of output schema and annotations, this description is remarkably complete, giving the agent all necessary information to decide when to call this tool 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?

Both parameters are already documented in the schema, but the description adds critical semantics for the `heading` parameter: exact string match after trimming, case-insensitivity, and that fuzzy/partial matches fail. It also clarifies the return body and error condition, which are not 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 explicitly states the action: 'Return the body of ONE heading' and lists the additional output fields. It clearly distinguishes this from sibling tools like `read_file_outline` and `read_file_lines`, which are mentioned as alternatives for different use cases.

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 instructs when to use alternatives: 'Pair with `read_file_outline` when you are unsure which headings exist; for non-heading line ranges use `read_file_lines`.' This provides clear when-to-use and when-not-to-use guidance, naming specific sibling 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?

With no annotations provided, the description carries full weight and does so thoroughly. It discloses side-effectfulness ('SIDE-EFFECTFUL: writes/updates/deletes file and FTS rows'), the destructive prune behavior, idempotency ('running twice is a near no-op'), skip criteria (>5MB, junk dirs), and absence of auth/rate limits. It also states the return shape, which is beyond what any schema/annotation offers.

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 yet information-dense, front-loading the core action in the first sentence. Each subsequent sentence adds distinct value (scope, side effects, idempotency, limits, use cases) without redundancy 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?

For a tool with a single optional parameter and no output schema, the description is fully complete: it explains the two scopes, the exact operations performed, safety constraints (never deletes files from disk), skip conditions, and expected return fields. It also connects to sibling diff_against_disk and external workflows, making it self-sufficient 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 coverage is 100% with the parameter description 'Project ID. Pass null or omit to reindex the Knowledge Base.' The tool description adds behavioral nuance: for a set project_id it 're-runs discoverFiles', whereas for KB it walks knowledge/ and handles new/modified/pruned files. This enriches parameter semantics beyond the schema's simple null/omitted directive, though the schema already covers the core meaning.

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 'Reconcile the FTS index against disk', a specific verb and resource that clearly distinguishes this tool from sibling tools like search, diff_against_disk, or list_files. It explicitly contrasts with diff_against_disk by saying 'Use after editing files outside Kontexta, or when diff_against_disk reports drift', making the purpose unmistakable.

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 when-to-use guidance: 'Use after editing files outside Kontexta, or when diff_against_disk reports drift.' It also clarifies scope (project vs KB) and states idempotency, helping the agent decide if this tool is appropriate versus alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states read-only nature, no side effects/auth/rate limits, default caps (500 files, 10 hits per file), truncation reporting, scoping semantics, and that invalid regex throws. This is comprehensive for a read-only tool.

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

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

Three dense sentences cover purpose, performance, safety, caps, truncation, scoping, and error behavior. No fluff; every clause adds value. Front-loaded with purpose, then operational details.

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 no output schema and no annotations, the description provides sufficient operational context: what it returns (per-file hits with line numbers), important caps and truncation flags, scope semantics, and error conditions. The agent can correctly invoke and interpret results.

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 80% (4 of 5 parameters have descriptions; case_insensitive has no description). The description adds little beyond the schema—it restates project_id semantics which the schema already covers. It doesn't add information about case_insensitive or the exact format of pattern beyond what the schema says. Baseline 3 for high schema coverage 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 clearly states what the tool does: 'Match a JS regex against the body of every file in scope... and return per-file hits with line numbers.' It uses a specific verb (match) and resource (files in scope). It also distinguishes itself from the FTS `search` sibling by naming it directly and positioning regex_search as a fallback for cases FTS misses.

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?

Explicit when-to-use guidance is provided: 'use only when FTS misses substrings, URLs, or code identifiers.' It also explains the performance tradeoff ('Slower than FTS search') and clarifies scoping behavior for project_id, which helps the agent choose scopes correctly. No exclusions are needed beyond this.

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

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

With no annotations, the description fully discloses side effects, including writing metadata to disk, recursive scanning, indexing markdown, registering Hands tools, and idempotency. It also states auth/rate limits (none), return format, and error conditions, providing complete transparency beyond what annotations would offer.

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 lengthy but well-structured with clear sections (SIDE EFFECTS, AUTH/RATE LIMITS, PARAMETERS, RETURNS, ERROR CONDITIONS). Every section adds value, and the use of headers improves scanability. It is slightly verbose but justified by 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?

This tool has no output schema and moderate complexity, but the description completely covers return values, error behavior, side effects, and prerequisites. The detailed RETURNS section lists every field, and ERROR CONDITIONS distinguishes fatal vs non-fatal issues. It is comprehensive enough for an agent to use the tool with confidence.

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 baseline is 3, but the description adds critical operational meaning beyond the schema. For the 'path' parameter, it explicitly warns against guessing from the editor workspace and instructs the agent to ask the user for the absolute path if uncertain. This goes beyond the schema's description and improves correct invocation.

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's function with a specific verb and resource: 'Register a new project and link it to the Kontexta knowledge system.' It distinguishes this from siblings like list_projects and refresh_index by detailing the registration and indexing side effects, making the 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?

The description provides clear usage context, such as requiring an absolute path and explicitly instructing to ask the user if only a project name is given. It does not explicitly name alternatives, but the tool's uniqueness among siblings makes this less critical. The guidance on when to ask for the path is a strong usage guideline.

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

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

With no annotations, the description fully covers behavioral traits: side effects limited to the running MCP session's tool inventory, no disk writes, idempotent, no external auth/rate limits, and return value summarized. Very thorough.

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 yet dense, with each sentence serving a purpose: main action, side effect, idempotence, auth/rate-limit note, return summary, and usage guidance. No filler or repetition.

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?

The tool is simple (zero params) but the description still covers all necessary context: what triggers it, what changes, side effects, return contents, and a pointer for schema details. It is complete 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 tool takes zero parameters and the schema confirms this. The description explicitly states 'Takes no parameters', which is a helpful reinforcement, but there is no additional parameter meaning to add beyond that.

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 ('Re-scan'/'rebuild') and resource ('live Hands tool registry'), explaining what changes: new tools become callable and removed tools disappear from tools/list. This clearly distinguishes it from sibling tools like list_hands or describe_hands_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?

Explicitly says when to use it: 'Use after editing a kontexta.json mid-session'. It also directs users to a sibling tool for a related but distinct need ('for the schema see describe_hands_schema').

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

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

With no annotations, the description fully discloses behavior: destructive only on the link, file and global tags preserved, idempotent no-op for absent tags, no auth/rate limits, and exact return value. It also clarifies the parameter type (integers) and that names are not accepted.

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, and every subsequent sentence adds distinct value—side effects, idempotence, return value, ID type, and alternatives—without redundancy 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?

For a two-parameter tool with no annotations and no output schema, the description is remarkably complete: it covers purpose, effects, return value, parameter semantics, and alternatives. No critical gaps remain for an agent to correctly select and invoke the tool.

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

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

Although schema coverage is 100%, the description adds meaning by specifying that tag_ids are integers and must be fetched via list_tags, and that multiple IDs can be passed. It also clarifies the semantics of removing an already-absent tag as a no-op.

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+scope: 'Detach one or more tag IDs from ONE file.' It distinguishes from siblings by explicitly naming tag_search_results as additive-only and noting there is no bulk-untag tool, and from add_tags by being the inverse 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?

It provides explicit when-to-use context: for detaching specific tags from a single file. It notes the alternative (tag_search_results) for bulk tag addition and clearly states there is no bulk-untag-by-query tool, preventing misuse. It also instructs to fetch IDs via list_tags.

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

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

With no annotations, the description fully discloses destructive behavior ('current uncommitted content is lost'), side effects ('file watcher may also pick up the change before this returns'), error cases ('foreign hashes throw'), and absence of external auth/rate limits. This far exceeds typical disclosure.

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 (~4 sentences) and front-loaded with 'DESTRUCTIVE.' Every sentence conveys a distinct fact: action, hash requirement, data loss risk, watcher side effect, auth/limits, return format, and use case. No fluff.

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 no output schema, the description states the return structure. It covers prerequisites, side effects, error conditions, and appropriate use cases. For a destructive restore operation with no annotations, this is thoroughly complete.

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

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

Schema coverage is 100% for both parameters, but the description adds crucial semantics beyond schema: the hash must come from get_history for this specific file, and foreign hashes cause an error. This is a meaningful addition to the schema's simple 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 states a specific action: 'Overwrite a file's current on-disk content with the version recorded at a specific git commit, then re-index FTS.' This clearly distinguishes it from siblings like update_file (editing) and delete_file (removal), and explicitly limits its use to 'undo accidental edits or recover a known-good version.'

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: 'Use only to undo accidental edits or recover a known-good version.' It also provides a critical prerequisite: 'The hash MUST come from get_history for THIS file (foreign hashes throw),' which guides correct invocation and avoids misuse.

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

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

With no annotations, the description carries the full burden and does so excellently: declares read-only status, no side effects/auth/rate limits, describes return fields (match_excerpt, title_highlight, total_est_tokens), and discloses FTS tokenization limitations.

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 well-structured; every sentence adds value. Front-loaded with core purpose, then limitations, parameter nuances, and alternatives. No fluff or repetition.

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 no output schema, the description explains return fields and aggregate. Covers usage, limitations, parameter semantics, and alternatives, making it complete for a search tool of this complexity.

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?

Although schema coverage is 100%, the description adds significant meaning beyond schema: clarifies that `project_id: null` restricts to KB only vs omitted spans all, that all tags must match, and that no follow-up `read_file` is needed for snippets.

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 action: full-text keyword search across files using FTS5. It distinguishes itself from siblings by explicitly naming `regex_search` and `bundle_search` as alternatives for different needs.

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: fall back to `regex_search` for URLs/hyphenated terms/partial substrings, and use `bundle_search` for prompt-ready bundled bodies. Also explains project_id semantics (null vs omitted) and tag matching 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?

With no annotations, the description carries the burden. It discloses idempotency, SQLite persistence, no external auth/rate limits, and the return shape. It doesn't mention error behavior for nonexistent file_id, but for a simple setter this is reasonably rich.

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 concise sentences cover purpose, idempotency, persistence, auth/rate limits, return value, and integration with other tools. No filler 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 simple two-parameter setter, the description covers behavior, return value, where it persists, and how it integrates with search/list filters. No output schema exists, but the return is explicitly stated. The tool is fully self-contained.

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% with basic descriptions like 'Favorite status'. The description adds critical meaning: 'not a toggle, you pass the desired state' and clarifies idempotency, which goes 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 'Set or clear the favorite flag on one file', a specific verb-resource pair. It also distinguishes this tool from siblings like add_tags/remove_tags by focusing on the favorite flag.

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 clear context: 'Use to curate quick-access pins' and mentions that list_files/search/bundle_search accept favorite:true for filtering. However, it doesn't explicitly state when not to use this tool or name direct alternatives, so it stops short of full 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?

With no annotations provided, the description carries the full burden. It explicitly states 'Read-only; no side effects, auth, or rate limits' and adds performance behavior for include_token_total ('measurably slower on large vaults'). It also discloses the conditional by_project breakdown, providing rich behavioral context beyond any 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?

Three sentences deliver high information density: purpose, parameters, side effects, performance caveat, and an alternative tool. Every clause earns its place, and the use of backticks for parameters improves scannability.

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 three optional parameters, no output schema, and no annotations, this description is remarkably complete. It covers purpose, usage, behavior, parameter nuances, side effects, auth, rate limits, performance, and alternatives, leaving little ambiguity for an agent.

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

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

The schema already documents all three parameters (100% coverage), so the baseline is 3. The description adds value beyond the schema by explaining the performance impact of include_token_total and clarifying that omitting project_id yields an additional by_project breakdown. However, top_tags receives no extra semantic context beyond the schema description.

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

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

The description starts with a specific verb and resource ('Aggregate counts for a scope') and lists concrete aggregates (file_count, untagged_count, favorite_count, top_tags). It also differentiates from sibling tools like diff_against_disk by referencing 'cheap dashboard' vs 'live disk-vs-index drift'.

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 tells when to use the tool ('Use as a cheap dashboard or to spot untagged content for cleanup') and when not to, naming an alternative: 'for live disk-vs-index drift use diff_against_disk'. It also explains the distinction between omitting project_id vs passing null.

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

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

With no annotations, the description fully discloses behavior: read-only, no side effects, no auth or rate limits, returns net-new suggestions, and explains the algorithm (FTS mining, stopword-filtered).

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 adds value, the main action is front-loaded, and the description is concise yet comprehensive with 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?

Given simple parameters and no output schema, the description completely covers return format, edge cases (empty suggestions), and usage notes, making it self-sufficient.

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 covers both parameters with descriptions; description adds default limit of 10, maximum of 50, and clarifies that limit controls suggestion count, providing meaningful context beyond 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 tool suggests tags for a file using FTS, distinguishes from sibling add_tags by noting suggestions are not auto-applied, and specifies it is read-only with no LLM or network usage.

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 guidance on when to use (tag suggestions for a file), when not (empty suggestions indicate need to bootstrap with add_tags), and mentions read-only nature and no side effects, aiding selection over 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?

With no annotations, the description discloses side effects ('additive, idempotent per tag'), safety details (files not modified beyond tag links), failure isolation ('errors[]'), absence of dry-run, and no external auth/rate limits. This provides comprehensive behavioral transparency.

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 longer than average but every sentence carries essential detail, from side effects to verification warnings to return shape. It is front-loaded with the core purpose and efficiently structured.

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 no output schema and no annotations, the description covers the return object, side effects, failure isolation, and usage constraints. It is nearly complete, but the untouched optional parameters (favorite, project_id) and the exact error format are minor omissions.

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 description adds meaning for add_tags (applied to every match), tags[] (scoping filter, not control), and query (FTS), complementing the schema's descriptions. However, it omits any mention of favorite or project_id, which lack schema descriptions, leaving a gap in 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 opens with 'Bulk-tag — run an FTS search and append add_tags to every matching file in one call', clearly identifying the action, resource, and scope. It differentiates from sibling tools like search and add_tags by framing it as a combined bulk 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?

Explicitly instructs 'ALWAYS run search with the same query first to verify the match set before tagging', providing a clear when-to-use alternative. Also clarifies that the tags[] filter scopes the search rather than controlling added tags, preventing misuse.

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

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

No annotations are provided, so the description fully discloses behavior: replaces content on disk, triggers FTS5 re-index, returns metadata with token counts, and operates locally without external auth or rate limits. This is comprehensive for a mutating tool.

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

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

The description is concise and front-loaded with the core purpose in the first sentence. Every subsequent sentence adds meaningful context (replacement behavior, re-indexing, return value, alternatives, param specifics) 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?

For a simple two-parameter tool with no output schema, the description covers all necessary aspects: purpose, effects, return value, alternative tool, and parameter constraints. It is fully sufficient for an agent to select and invoke the 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 coverage is 100% with basic field descriptions ('File ID', 'New content'), but the description adds essential semantics: 'id' must be a valid integer, and 'content' is the complete markdown string that will replace the file. This clarifies constraints 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 verb and resource: 'Update the entire content of an existing file by its ID.' It clearly distinguishes from the sibling 'update_file_section' by explicitly contrasting full-file replacement vs. section modification.

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 provides when-to-use and when-not-to-use guidance: 'If you only need to modify a single section without replacing the entire file, use "update_file_section" instead to save context budget.' Also notes local operation with no auth or rate limits.

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

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

With no annotations, the description carries full burden and delivers: persistence path (writes to disk → FTS reindex → git commit), error behavior (throws if heading doesn't exist), matching semantics (case-insensitive exact-string), and return value (updated file metadata). It also states 'No external auth or rate limits', which is a useful baseline disclosure.

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 a one-line summary and each subsequent sentence adds distinct value: preservation behavior, persistence, error condition, scoping, and alternatives. No redundant clauses; it's appropriately sized for the 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?

Despite no output schema, the description covers return value, side effects, error handling, edge cases (case-insensitivity), and sibling relationships. It is complete for a mutation tool with zero 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?

Schema coverage is 100% with clear descriptions for all three parameters. The description adds marginal context like 'exact-string' for heading and reinforces that content is the new body, but the schema already captures these meanings. Baseline 3 is appropriate since the schema does the heavy lifting.

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: 'Surgical write — replace the body of ONE heading without touching siblings.' It clearly distinguishes from `update_file` by scoping to one heading and explicitly mentions the alternative for full-file replacement.

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 provides explicit when-to-use guidance: 'Use to make targeted edits without re-sending the whole body; for full-file replacement use `update_file`.' It also warns against using it to create new sections, directing to `update_file` instead, which serves as a clear exclusion.

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

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

With no annotations provided, the description carries the full burden and delivers richly: it states 'Read-only; no side effects, auth, or rate limits,' warns that invalid `since` formats throw, explains the mtime-driven caveat for hard-deleted files, and discloses the return value including `total_est_tokens`. This is exemplary transparency.

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, followed by format specs, safety profile, return insight, caveat, defaults, and a usage hint. There is no repetition 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?

For a read-only list tool with no output schema, the description covers the full context: when to use it, how to format parameters, what it returns, its safety, and its limitations. An agent can confidently select and invoke this tool based solely on this description.

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% for all four parameters, but the description adds significant meaning beyond the schema: it explains `since` accepts both ISO-8601 and relative durations, clarifies the distinction between `project_id: null` and omitting it, and states defaults for `include_tags` and `limit`. This goes above the baseline of 3.

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+scope: 'List files created or modified since a checkpoint.' This clearly distinguishes it from sibling tools like list_files (which probably lists all files) and search (which might be content-based). No ambiguity.

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 a clear when-to-use: 'Use at session start to catch up,' and a when-not via the caveat 'hard-deleted files are NOT surfaced.' However, it does not explicitly name an alternative tool for when a different behavior is needed, like search or list_files, so it falls just 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.