kontexta

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, and it excels. It explicitly warns 'SIDE-EFFECTFUL — TOUCHES THE NETWORK,' explains auth relies on local git credentials, states idempotency (no-op commit skipped but push still runs), lists failure modes (throws on missing repo or push failure), and specifies the return object. This is exemplary transparency for a mutation 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, front-loading the critical side-effect warning, then explaining the action, auth, idempotency, errors, return value, and usage. Each sentence adds value, though it is somewhat lengthy. It could be slightly tightened, but the length is justified for a complex, side-effectful tool.

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 complete for the tool's complexity: it covers the operation, auth prerequisites, idempotency, error conditions, return value, and recommended usage. The input schema is trivial (one required param), and the output schema is absent but the return object is described. Nothing an agent needs to call it correctly is missing.

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

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

The schema covers the only parameter (project_id) with 100% coverage, so the baseline is 3. The description adds minimal context by referring to 'the project's KB data,' which reinforces that project_id identifies the project, but it does not provide additional syntax or format details beyond what the schema already conveys.

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: 'Sync the project's KB data into its git backup directory, create a commit, and `git push` to `origin`.' This clearly distinguishes it from all siblings, none of which perform backup/commit operations. It is not a tautology and leaves no ambiguity about the tool's function.

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 'Use after a batch of KB writes to get changes off-machine,' which provides clear when-to-use guidance. It also implies prerequisites (e.g., configured backup repo) by noting the tool throws if none exists. However, it does not explicitly mention when not to use it or name alternative tools, though no direct alternatives exist among the siblings, so this 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 provided, the description carries the full burden of behavioral disclosure. It clearly states 'Read-only; no side effects, auth, or rate limits' and enumerates the return data categories, giving an agent a complete behavioral picture.

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 tightly packed sentences with no filler. The most essential facts—what it returns, that it's read-only, and when to use it—are front-loaded.

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

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

For a zero-parameter read-only tool, the description covers the core purpose, usage timing, safety profile, and return contents. There is no output schema, so the listed return categories ('existence status, full content, list of missing required sections, and a hint for new users') are 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 tool has zero parameters, so there is no parameter semantics burden. The baseline for 0-param tools is 4, and the description appropriately avoids inventing parameter details it doesn't need.

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

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

The description opens with a specific verb and resource: 'Return the user profile stored in the Knowledge Base.' It clearly differentiates this tool from other admin tools by focusing on the user profile, and the read-only scope is immediately apparent.

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 at session start to understand who you're working with,' providing clear context for when to invoke this tool. It does not name alternatives or state when not to use it, but the usage context is precise enough.

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 for disclosing side effects. It does so well: it flags file mutation, guarantees idempotency via fenced markers + version, requires explicit user consent, and summarizes the returned status objects. It could add more about failure modes or whether existing rules are replaced vs merged, but 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?

The description is compact and well-structured: purpose sentence, consent warning, parameter list, and return shape. Every block adds needed information. It is somewhat long but the complexity of the tool justifies it; the parameter section partially duplicates schema descriptions but adds mode logic that is not present there.

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, modes, required consent, parameter conditions, and the return format in one place. It is sufficient for an agent to call the tool correctly in most cases. Minor gaps exist around exact behavior when both files and target_agent are supplied, and there is no explicit statement about which files are affected when no files are given, though these are inferable from the parameter notes.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining conditionals: files defaults to recommendation.target_files in update mode, is ignored when empty with target_agent, and target_agent selects canonical filename + scaffold when no context file exists. This adds meaningful semantic nuance beyond the JSON 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 opens with a specific verb-resource pairing: 'Write or update the kontexta workflow rules block in a project's agent context file(s).' It clearly distinguishes this from generic file tools by naming the exact domain artifact and intended operation. The name alone is not relied upon; the description expands it into actionable 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?

The description gives clear operational guidance: it states that consent is mandatory before invoking, describes create vs update modes, and explains when target_agent is required. It does not explicitly name alternative sibling tools or say when NOT to use this tool, so it stops short of a full 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 in the tool definition, the description carries the full burden of behavioral disclosure and does it thoroughly. It states that the tool is 'Read-only; no side effects, auth, or rate limits.', mentions that `include_token_total: true` is 'measurably slower on large vaults', and discloses that hard-deleted files are not surfaced in whats_new and invalid `since` formats throw errors. These are precisely the behavioral traits an agent needs to know beyond simple schema semantics.

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 extremely well organized: the purpose opens the description, followed by mode-specific details, then performance caveats, then explicit usage guidance. Every clause adds a concrete fact (e.g., 'ISO-8601 ... or relative durations', 'top_tags default 10') without filler or repetition of the schema.

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

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

Given the tool has 7 parameters, two modes, and no output schema, the description covers modes, parameters, performance, failure modes, and usage guidance—an unusually complete definition for such a complex tool. The only minor gap is that the return shape is partially implied (e.g., 'also returns by_project breakdown', 'list files') but not precisely specified, and an agent is left to infer the exact JSON structure of the file entries in `whats_new` mode.

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 describes all 7 parameters with 100% coverage, so the baseline is 3. The description adds meaningful semantics beyond that: per-mode parameter roles (e.g., `limit` is 'whats_new only'), the `project_id` distinction between 'null' vs 'omitted', and performance implication for `include_token_total`. It does not restate the schema but adds explanatory context, justifying a 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 'Vault-state snapshot' and then enumerates two specific behaviors: 'mode: stats' returns aggregate counts (file_count, untagged_count, favorite_count, top_tags) and 'mode: whats_new' lists files created or modified since a checkpoint. It also differentiates itself from the sibling tool by pointing out `files.diff_against_disk` for live disk-vs-index drift, so an agent can select it unambiguously.

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 guidance is embedded in the description: 'Use stats as a cheap dashboard or to spot untagged content for cleanup' and 'use whats_new at session start to catch up' are direct instructions. It also names an alternative for a specific case ('for live disk-vs-index drift use files.diff_against_disk'), leaving no ambiguity about when to choose this tool.

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

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

With no annotations provided, the description fully carries the burden. It explicitly states 'Read-only; no side effects' and clarifies that the return value is the same block sent as MCP instructions at session start. This is strong, unambiguous behavioral disclosure for a zero-parameter read operation.

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 dense, front-loaded sentences: the first defines the operation and contents; the second gives the trigger, safety behavior, and return shape. 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 zero-parameter refresh tool with no output schema, the description is complete: it names the trigger, the refreshed data, the side-effect profile, and the return shape. An agent has everything needed to decide 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?

There are zero parameters, so there is nothing for the description to add beyond the schema. Per calibration, a zero-parameter tool receives a baseline of 4, and the description appropriately focuses on behavior instead of parameters.

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-read') and resource ('session context'), and enumerates the contents: profile, upcoming events within 7d, conflicts, freshness nudge. This clearly distinguishes it from siblings like admin.get_profile or calendar.events.*, which cover narrower domains.

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

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

Gives an explicit trigger: call when the user just edited their profile or added/moved calendar events and you need the current picture instead of the session-start snapshot. It lacks explicit 'do not use when...' phrasing or named alternatives, but the usage context is 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, and it does so thoroughly. It explicitly discloses that the tool never deletes or modifies originals, writes new files into Kontexta's data dir, requires user consent, is idempotent via SHA-256 comparison, and never performs destructive filesystem operations against project.path.

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 uses labeled sections for parameters, returns, and idempotency, making it navigable. It is somewhat verbose and repeats the non-destructive guarantee multiple times, but for a consent-required write operation, that redundancy is defensible and not wasteful.

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?

Even with no output schema, the description fully documents the return shape, skip reasons, consent requirements, and idempotency behavior. It covers edge cases such as symlinks, missing files, and outside-project paths. This is complete enough for an agent to invoke the tool safely and interpret its 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 description coverage is 100%, so the baseline is 3. The description's PARAMETERS section mostly restates the schema's own descriptions. It adds a small amount of context, such as tying 'files' to the detection list used by register_project/onboard_agent, but it does not substantially enrich 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 a specific action, 'COPY existing agent context files... into Kontexta's per-project knowledge base', with concrete examples of file types. It distinguishes itself by emphasizing 'ONLY COPIES', but it does not fully differentiate itself from sibling admin.onboard_agent, which it references by name for the detection list but without explaining the boundary between the two 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 usage conditions: mandatory consent before calling, how to select files with the optional 'files' parameter, and the idempotent re-run behavior. It gives clear context for when to call, though it does not explicitly state when not to use this tool or name an alternative tool for a different situation.

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 exist, so the description carries the full burden; it leads with SIDE-EFFECTFUL, discloses non-idempotence, duplicate-name failure, and return shape. This goes well beyond what the schema reveals.

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 tight sentences, each earning its place: side-effect alert, definition/examples, uniqueness/failure behavior, return value, and next-step routing. It is 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?

For a simple 4-param create tool with no output schema, it covers behavior, errors, return shape, and follow-up workflow. Nothing essential for correct invocation is missing.

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

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

Schema already documents all four parameters at 100% coverage, so baseline 3 applies. The description adds semantic context for the entity resource but no new parameter-level details beyond what the schema provides.

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

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

Clearly identifies the verb ('Create') and resource ('new tracked entity'), defines what an entity is with concrete examples, and is distinct from siblings like calendar.entities.update, delete, and link.

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?

States when to use it (to create a tracked thing) and explicitly directs the next step to calendar.entities.link for dependency recording. It doesn't enumerate exclusions (e.g., use update for existing entities), but the duplicate-name warning implies when not to re-create.

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 delivers. It discloses that the operation is destructive, permanent, cascade-deletes children, is not idempotent, throws on unknown ids, and returns a shaped response. This fully compensates for the lack of annotations.

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

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

The description is compact and front-loaded, opening with 'DESTRUCTIVE' to immediately flag the risk. Every sentence earns its place: destruction scope, non-idempotency, return value, error behavior, and the safer alternative. 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 tool with one simple parameter and no output schema, the description explains the return object, error behavior, non-idempotency, and the alternative. It gives any agent everything necessary to call this tool safely and correctly, with no gaps requiring inference.

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 single id parameter is fully described in the schema ('Entity id to delete'). The description does not need to add meaning to the parameter itself. Its mention of the return value and errors is behavioral, not parameter semantic, so a baseline 3 is appropriate.

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

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

The description states a specific verb ('delete'), resource ('entity'), and scope ('cascade-delete every event and link attached to it'). It distinguishes itself from calendar.entities.update and calendar.events.delete by explicitly clarifying the destructive, cascading behavior and naming the safer alternative.

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 names when to use it versus the alternative: 'To deactivate without losing history, use calendar.entities.update with active: false instead.' It also warns that the operation is not idempotent and throws on unknown ids, giving clear behavioral criteria for choosing this tool.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It flags itself as SIDE-EFFECTFUL, documents idempotent upsert behavior, states that removing an absent link is a no-op, and specifies the return shape `{link}` or `{removed}`. It also reveals the directed nature and one-hop traversal, which is rich context beyond the schema.

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

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

The description is compact and information-dense: it covers the core action, the remove toggle, idempotency, no-op behavior, the use case, and the return type in four clauses. There is no filler, and the most critical information is front-loaded.

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

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

Given that the tool has no annotations and no output schema, the description covers everything an agent needs: mutation semantics, edge direction, idempotency, no-op case, integration relevance, and return shape. The parameters are fully documented in the schema, so nothing is left ambiguous or 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 already documents all four parameters with 100% coverage, so the baseline is 3. The description adds meaningful behavioral semantics: `remove: true` toggles from create/update to removal, and the directed edge concept maps directly to from/to. It also clarifies that repeat calls upsert the label, which is not present 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 opens with a precise action: 'Create or update a directed dependency edge between two entities, or remove one'. This clearly distinguishes the tool from sibling entity CRUD tools (add/update/delete/list) by naming the resource (edges) and the verbs (link/create/update/remove). The example 'A feeds B' concretely illustrates intent.

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 the integration purpose: 'Used by calendar.events.conflicts/calendar.events.list to flag overlaps across connected entities (one hop, either direction)'. This gives a strong contextual signal for when the tool matters, but it does not explicitly name alternatives or say when not to use it. Still, the context is clear enough for an agent to infer its role.

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?

Since no annotations are provided, the description carries full burden. It explicitly states 'Read-only; no side effects, auth, or rate limits' and details the return shape ('Returns {entities, count}'), going beyond a basic read-only hint. This is strong disclosure that the agent can rely on.

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, tightly packed sentence that front-loads the read-only guarantee and return type. Every clause adds value, with no fluff. It is an exemplar of concise yet informative writing.

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 listing tool with 2 optional params and no output schema, the description covers safety, return format, and resource type. Sibling tools indicate a full ecosystem, but this tool's description is sufficient for an agent to invoke it correctly without additional 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 both 'kind' and 'active_only' are documented in the schema. The description adds no additional parameter details, but the schema fully covers them, meeting the baseline of 3. No extra compensation 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 clearly states the tool lists tracked entities and includes dependency annotations, distinguishing it from sibling tools like calendar.events.list. It uses a specific verb ('List') and resource ('tracked entities'), 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 indicates this is a read-only listing tool for entities, but does not explicitly exclude scenarios where the alternative list tools should be used. However, the sibling list of calendar tools implies this is the go-to for entity listing, and 'Read-only' signals it's safe to call. No explicit when-not, but the context is adequate.

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

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

The description discloses key behavioral traits: it is 'SIDE-EFFECTFUL' (a warning), idempotent per patch, and returns `{entity}`. It also explains the soft-retire behavior (set `active` to false without losing history). Since no annotations are provided, the description carries the full burden, and it does so well by flagging side effects and idempotency. It could mention whether patches are partial (only provided fields updated) but the schema implies that.

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: it starts with the side-effect warning, then the action, then the key behavioral details (idempotency, return value), and finally the alternative. Every sentence earns its place, and it's compact enough for an agent to parse quickly.

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 (6 params, 1 required, no output schema), the description covers the essential behavioral aspects: side effects, idempotency, return shape, and the soft-retire distinction. It doesn't explain the return format in detail (e.g., what fields `{entity}` contains), but that's likely inferable from the entity context. The lack of an output schema is partially compensated by the `{entity}` return mention. A 4 is fair because it's complete for an agent to call it correctly, though a bit more detail on partial patch semantics would push it to 5.

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

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

Schema description coverage is 100%, so the schema already documents all 6 parameters. The description adds value by explaining the `active` field's soft-retire semantics, which is not fully captured in the schema ('Set false to soft-retire the entity without losing history' appears in both, but the description emphasizes it). However, the description doesn't add much beyond the schema for other parameters, so a baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Patch an existing entity's fields' with a specific verb ('Patch') and resource ('existing entity's fields'). It also distinguishes itself from the sibling `calendar.entities.delete` by explicitly noting the difference between soft-retire and hard delete. The mention of `active` field and soft-retirement adds specificity.

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

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

The description provides clear context for when to use this tool: to update an entity's fields, including soft-retiring via `active: false`. It explicitly contrasts with `calendar.entities.delete` for hard delete, which serves as an alternative. However, it doesn't explicitly state when NOT to use it (e.g., for creating entities, which is `calendar.entities.add`), though the sibling list makes that inferable.

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

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

Annotations are absent, so the description carries the full disclosure burden. It opens with 'SIDE-EFFECTFUL', warns 'NOT idempotent — calling this twice creates two events', explains why naive timestamps are rejected, and states the return value. This makes the side-effect and idempotency profile transparent before invocation.

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 dense sentences lead with the most decision-relevant fact (side-effectful/non-idempotent), then move to preconditions, return value, and recommended follow-up. Every sentence earns its place with 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 moderately complex (8 params, no annotations, no output schema), yet the description covers side effects, idempotency, timestamp constraints, return shape, and the recommended next step. There is little an agent needs to safely invoke it correctly; only explicit error behavior for nonexistent entities is absent, which is minor.

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

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

The input schema already documents all 8 parameters, so the baseline is 3. The description adds value by explaining rejection semantics for naive starts_at/ends_at timestamps and clarifying the 'one-off' nature of the window. It doesn't add much for entity, notes, source, or original_timezone, but the schema already covers those.

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 ('Add') and resource ('one-off time window'/'event') with concrete examples such as downtime, maintenance, and shift. It clearly differentiates from sibling event tools (update/delete/list/conflicts) by framing the action as creating a new event, and it highlights non-idempotence as a distinguishing trait.

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

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

It states the context for use: adding one-off time windows to an entity, and it explicitly directs the agent to follow up with calendar.events.conflicts for overlap checks. It also establishes a hard precondition (ISO 8601 with explicit timezone) that an agent must verify before calling. It does not explicitly mention alternatives like events.update for modifications, but the sibling separation is otherwise 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 and meets it fully: it declares read-only, no side effects, no auth, no rate limits, on-demand computation, non-persistence, and the exact return shape `{conflicts, count, buffer_minutes, events_considered}`. It even doc both the default buffer setting and that 0 disables the check. Nothing is left to inference.

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 dense sentences, each earning its place: safety profile up front, then purpose/conflict taxonomy, then configuration semantics, then return shape. No filler; the most decision-relevant fact (read-only/no side effects) is front-loaded.

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

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

For a no-annotation, no-output-schema tool with 4 params, the description is complete: window parameters, optional scoping, buffer override, default setting source, return shape, and a pointer to the related tool. An agent has everything needed to call it correctly without opening any other schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value beyond the schema: it explains `buffer_minutes` overrides the `calendar.min_buffer_minutes` setting (and the 0 = off semantics), and clarifies that `entity`-scoped conflict checking operates one hop out to linked entities. This is above the baseline without duplicating schema text.

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?

"Report scheduling conflicts in a window" names a specific verb + resource, then enumerates the three conflict types (`overlap`, `linked_overlap`, `insufficient_buffer`). This is clearly distinguishable from siblings like `calendar.events.list` and `calendar.events.add` without inspecting their schemas.

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

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

The description gives strong contextual guidance: read-only, computed on demand, nothing persisted, and explicit about when buffer behavior applies. It names the alternative (`calendar.events.list` with `include_conflicts`) but does not spell out the exact condition that would make an agent choose one over the other — it is closely implied but not explicit.

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 labels the tool DESTRUCTIVE, states idempotency (deleting an already-absent id is a no-op), and describes the return value as `{success, existed}`. This discloses key behavioral aspects: permanence, safety on non-existent ids, and return shape. However, it omits permissions, reversibility, and any side effects on related data, which are relevant for a delete tool, so it falls short of a 5.

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 exceptionally concise, with each sentence adding distinct value: it front-loads the destructive nature, then states the action, then idempotency, then the return shape. There is zero redundancy or filler, and the most important information appears 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?

For a simple delete operation with one parameter, the description covers the essential context: what it does, destructive behavior, idempotency, and return value. It does not detail error handling (but idempotency implies no error for missing ids), permissions, or reversibility, though these are not critical for a basic delete. The description is nearly complete but could mention permanence explicitly, hence a 4 rather than a 5.

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 fully documents the single parameter id with description 'Event id to delete,' and schema coverage is 100%. The description adds no additional meaning beyond the schema, such as format, validation, or examples. Since the schema is comprehensive, the baseline 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 clearly states the verb (Delete), the resource (event), and the scope (one event by id). It distinguishes from siblings like calendar.events.update, list, and add, and even from calendar.entities.delete, by specifying event id. It is precise 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 provides no guidance on when to use this tool versus alternatives. It does not mention conditions like 'use this to remove an event, but use calendar.events.update to modify it,' nor does it mention any restrictions or preconditions. There is no reference to alternatives or when not to use it, leaving usage context entirely to the agent's inference.

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

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

With no annotations, the description carries full responsibility. It explicitly declares read-only, no side effects, auth, or rate limits. It discloses the half-open window boundary condition and the behavior of include_conflicts. It also specifies the return shape. This is comprehensive transparency 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 concise, four sentences, with zero waste. It front-loads the safety guarantee, then states the core action, optional filters, conflict inclusion behavior, return shape, and alternative routing. Each 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?

For a list operation with 6 parameters and no output schema, the description covers the essential return shape, window semantics, filtering, and conflict behavior. It does not mention pagination details beyond the limit parameter, but the schema covers that. The only minor gap is lack of explicit error/edge-case handling, but that is not critical for a read-only list tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics: the half-open window definition (event ending exactly at 'from' is excluded) clarifies the from/to parameters. It also explains that include_conflicts requires both from and to and attaches conflicts to the response. This goes 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 clearly states the verb (list) and resource (events) with a specific window definition. It distinguishes itself from sibling tools by explicitly naming the alternative for conflict-only queries. The half-open window semantics and optional filters make 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?

Explicitly states when to use an alternative: 'For conflicts alone, prefer calendar.events.conflicts.' It also implies safe usage with 'Read-only; no side effects, auth, or rate limits.' The context of filtering and conflict inclusion is clearly scoped, leaving no ambiguity about when this tool is appropriate.

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

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

With no annotations, the description carries the full burden and does well: it flags SIDE-EFFECTFUL, explains that the merged result is re-validated, and warns that shrinking ends_at below starts_at throws. It also states the return shape `{event}`. It could add permission or conflict details, but the core behavioral risks are disclosed.

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 tight sentences, front-loaded with the safety-critical SIDE-EFFECTFUL marker, then examples, validation behavior, and return shape. Every sentence earns its place 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?

The schema fully documents all 9 parameters, and the description covers patch semantics, validation, and return value. It is complete enough for a straightforward partial update; missing niceties like auth requirements or conflict behavior are not essential for invoking it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a cross-parameter constraint not present in the schema: the merged result is re-validated and shrinking ends_at below starts_at throws. This gives meaningful semantics beyond the individual field 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 uses a specific verb and resource: 'Patch an existing event', and gives concrete examples (move it, retitle it, re-home it). This clearly distinguishes it from sibling tools like calendar.events.add, calendar.events.delete, and calendar.events.list.

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 states this is for modifying an existing event, not creating or deleting one. It doesn't explicitly name alternatives or exclusion conditions, but the context is clear enough that an agent can route to it versus add/delete/list.

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 delivers richly: it states the tool is 'Read-only; no side effects, auth, or rate limits', discloses timezone handling ('UTC times, no VTIMEZONE needed'), and specifies the return shape ('{ics, event_count}'). This goes well beyond the bare minimum and 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?

Three sentences cover safety, format, use case, timezone behavior, and return type without redundancy. The read-only note is front-loaded, and every sentence carries distinct information. 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 an export tool with no output schema, the description fully explains what the agent needs to know: the operation type, the output format and its quirks (UTC, no VTIMEZONE), the return payload, and the intended use. Required parameters are described in the schema, and the description does not omit critical behavioral information.

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 parameters (from, to, entity, calendar_name) are already documented in the schema. The description adds no additional parameter-level detail beyond the window concept already expressed in the schema. Baseline 3 applies because the description does not degrade or add meaningful semantics.

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 ('Export'), a resource ('events in a window'), and a concrete output format ('RFC 5545 ICS calendar'). It also states the intended downstream use (import into Outlook/Calendar apps), which distinguishes it from sibling tools like calendar.events.list. There is no ambiguity about what this tool produces.

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

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

The description gives clear context for when to use the tool: 'for import into Outlook/Calendar apps' and 'Export events in a window'. It does not explicitly name alternatives or exclusions, but the use case is specific enough that an agent can infer when this is appropriate. A slight deduction for not explicitly contrasting with calendar.events.list or mentioning that it is not for general event listing.

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 behavioral burden, and it does so thoroughly. It discloses side effects (writes to disk, adds to SQLite FTS5 index), auth and rate-limit context (none apply), error isolation semantics (per-item failures in errors[]), return shape ({created_count, error_count, created, errors}), and automatic directory creation. This is far beyond what the schema alone conveys.

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

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

The description is long, but the tool has many routing rules and conditional requirements that justify the length. It is front-loaded with the core purpose and max batch limit, then progressively covers destinations, error isolation, return values, and format specifics. A small amount of redundancy with the schema (e.g., single-element array note, kind rubric) keeps it from a perfect 5.

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

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

For a tool with no output schema and no annotations, the description is remarkably complete: it specifies acceptable destinations, required and optional parameters, format-specific routing, batch size limits, error behavior, return shape, auth/rate-limit status, and the sibling to use for modifications. An agent has enough information to invoke the tool correctly in all supported 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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: the single-element array convention, the kind rubric for dictionary vs note, destination-specific project_id requirements, auto-routing for mmd and html formats, and the fact that format defaults to 'md'. These are operationally critical details that would otherwise be easy to miss or misinterpret.

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: 'Create one or more markdown, mermaid, or HTML files in the knowledge base or project.' It immediately differentiates from siblings like files.update and files.delete by defining this as the creation operation, and it scopes the max batch size (200) and supported formats.

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?

Usage guidance is explicit: 'To modify an existing file, use files.update instead.' It also gives clear conditional routing rules for each destination ('project' or 'kontexta' require project_id; 'knowledge' requires kind for md files), and explains when format='mmd' or 'html' should be chosen. An agent can decide to use this tool versus alternatives without ambiguity.

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 destructive permanence, the non-idempotent behavior, per-item error isolation, partial-success semantics, the exact return shape, and the difference between KB file deletion (disk + FTS5 index) and project reference file deletion (index only). It also notes no external auth or rate limits. This is rich behavioral context beyond what any schema could convey.

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: destructive warning, batch limit, file-type behavior, non-idempotence, error isolation, return shape, and alternatives. It is front-loaded with the DESTRUCTIVE warning. It is longer than the HIGH calibration example, but the tool's complexity justifies the length; still, a couple of clauses could be tightened.

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

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

For a destructive batch mutation with no annotations and no output schema, the description is complete: it covers the return shape, error semantics, partial success, file-type differences, and safe alternatives. An agent has everything needed to invoke it correctly and to decide whether to call it at all.

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 schema already documents the ids array, min/max items, and the single-element case. The description reinforces the single-element array point and adds the 500-per-call limit, but it does not add meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Permanently delete'), a resource ('one or more files by ID'), and a concrete scope (up to 500 per call). It also distinguishes the two file types (KB files vs project reference files) and explicitly contrasts with sibling tools like tags.remove and files.list, so an agent can tell it apart without opening the 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?

The description explicitly says when to use this tool ('Use only when the file is truly obsolete') and when not to ('to deprioritise without losing data, untag or unfavorite instead'). It also names the alternative tools (tags.remove, tags.set_favorite) and gives a preview workflow via files.list. This is explicit when/when-not guidance.

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

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

No annotations are present, so description must disclose behavior. It states no token cost, local operation, no auth/rate limits, and lists the metadata fields it returns. This covers safety and scope. Missing error handling or return format, but for a read-only metadata fetch this is acceptable.

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 packs multiple pieces of information (no token cost, field list, local operation, use case, param requirement) in a compact paragraph. It leads with the core value proposition and avoids redundant filler. Each sentence contributes.

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 lists the key metadata fields returned, so an agent can infer what 'everything' includes. It also clarifies the non-content nature. Without an output schema, this is sufficient for a simple metadata tool. The usage note makes it clear when to use 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 covers the single 'id' parameter fully with a description. The description adds that 'id' must be a valid integer, reinforcing the type but not adding new meaning beyond the schema. With 100% schema coverage, baseline is 3; description adds marginal 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?

States a specific verb ('Return everything about a file') and resource, and explicitly contrasts with files.read by noting it does not pull content. Names the relevant sibling alternatives in usage, making it clear what it is not (a content reader).

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: when you'd otherwise chain multiple read/list calls just to decide whether to read the file. This provides a clear decision rule and implies not to use it for getting content. Also notes it operates locally with no auth/rate limits, which affects suitability.

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 explicitly states 'Read-only; no side effects, auth, or rate limits', which is thorough. It also clarifies what the tool does NOT return ('NOT a full diff'), preventing unrealistic expectations. Minor gap: it doesn't detail the exact structure of the output beyond listing fields, but the core behavioral characteristics are well 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?

Description is concise and structured; the first sentence states the purpose, followed by status list and return details, then usage guidance. It is front-loaded with the primary purpose and status enumeration. Slightly dense but no wasted words; each sentence adds value.

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

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

For a tool with a single parameter, full schema coverage, and no output schema, the description covers everything an agent needs: purpose, statuses, return fields, exclusions, usage triggers, and remediation. It is complete enough to call correctly and interpret results. Minor deduction for not detailing the output format precisely, but the essentials are present.

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

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

Schema coverage is 100%, so the schema already documents the file_id parameter. The description does not add much beyond the schema—it implies the parameter is a file identifier but doesn't specify how to find or validate it. Given the high coverage, a baseline 3 is appropriate; the description doesn't need to compensate.

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?

Clearly states the diagnostic purpose: detect drift between disk content and FTS index, and enumerates the possible statuses. It explicitly distinguishes itself from files.get_diff, preventing confusion with that sibling. The verb 'diagnose' and resource 'file' are 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?

Provides explicit guidance on when to use ('when search results look stale') and what to do if divergence is found ('run projects.refresh_index'). It also directs to files.get_diff for full diffs, covering both when-to-use and when-not-to-use. This is exemplary.

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 meets it: it declares read-only behavior, no side effects, no auth, and no rate limits. It also discloses return shape (`shared_tag_count`, `shared_tags`) and empty-result semantics, giving the agent strong 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 compact and every sentence earns its place: core action, safety profile, return fields, empty-result guidance, alternatives, and parameter notes. It is front-loaded with the main purpose and avoids 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?

Even without an output schema, the description tells the agent exactly what to expect from the return value and how to interpret an empty result. It also covers fallback tools and parameter behavior, leaving no practical gaps for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents `file_id`, `kind`, and `limit`. The description restates `kind` and the default limit but adds no meaning beyond the schema, so the baseline 3 is appropriate.

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

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

The description opens with a concrete verb-resource pair: 'Find other files sharing tags with the given file,' and adds ranking by `shared_tag_count` descending. It clearly distinguishes this tag-based relation tool from content-search siblings like `files.search` and `files.regex_search`.

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

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

It explicitly names alternatives and the conditions that select them: empty results mean fall back to `files.search`/`files.regex_search` for content discovery, or `tags.suggest` to bootstrap labels. It also states how `kind` narrows results and what the default limit is.

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 declares read-only, no side effects, no auth, and no rate limits; it discloses error behavior ('Throws if either hash is unknown to the file's repo'); and it explains the semantic consequence of argument order (inverting the diff).

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 short, high-signal sentences are front-loaded with the core purpose and then deliver safety, ordering, error, and usage guidance in order. There is no filler or repetition of the schema.

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

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

For a simple 3-parameter, read-only diff tool with no output schema, the description covers the operation, workflow context, safety profile, error behavior, and argument semantics. The return value ('unified diff') is self-descriptive to an agent, so nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful usage context: it tells the agent that hashes 'typically [come] from files.get_history' and explains the practical effect of ordering them. It also relates the parameter to error behavior (unknown hashes throw), going beyond the schema's individual field 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 precise verb-resource-object statement: 'Return the unified diff of one file between two commit hashes.' It clearly scopes to a single file and a diff between two commits, and it distinguishes itself from the sibling files.get_history by explicitly positioning this as the tool to see WHAT changed rather than just THAT it changed.

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 files.get_history to see WHAT changed, not just THAT it changed,' naming the exact prior step and contrasting its purpose. It also provides parameter-usage guidance, stating that commit_a is treated as the earlier side and that reversing the arguments inverts the diff.

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 covers it thoroughly: read-only, no side effects, no auth, no rate limits, which repo is read for which file type, exact return shape, and the meaning of an empty history array. No behavioral question is left unanswered.

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 dense sentences with zero filler. The core action and ordering are front-loaded, followed by repo behavior, return format, and usage guidance, each sentence earning its place.

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

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

For a simple one-parameter tool with no output schema, the description is complete: it explains the result format, empty-array semantics, repo resolution, read-only safety, and relationship to sibling tools. Nothing an agent needs to select and invoke it correctly is missing.

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

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

Schema coverage is 100% and the single parameter file_id is already documented as 'ID of the file'. The description adds some useful context about which repo the ID refers to, but does not substantially extend parameter semantics beyond the schema.

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

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

States a specific verb and resource: 'Return the git commit history for one file (newest first)' with the exact entry fields. It also distinguishes itself from sibling tools by naming files.get_diff and files.restore as complementary rather than equivalent 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?

Explicitly says when to use it ('to understand a file's evolution before editing or restoring') and names alternatives: pair with files.get_diff for line changes, use files.restore to roll back. This directly answers when-to-use vs 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 does so admirably. It declares read-only semantics, the absence of side effects/auth/rate limits, the per-row annotation fields, and the presence of `total_est_tokens` in the response. It also explains the `project_id: null` behavior which is a non-obvious trait.

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 carries distinct, non-redundant value: purpose, safety, response shape, special-case semantics, and sibling routing. The critical scoping constraints (`project_id: null` vs omit) appear early, and the whole description is dense but not verbose.

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 adequately explains the return format (per-row annotations plus `total_est_tokens`). All 8 parameters are semantically covered across schema and description, safety traits are disclosed, and guidance for selecting among relevant siblings is included. Nothing an agent needs to call this tool correctly is missing.

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

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

The schema already covers 100% of the parameters, so the baseline is 3. The description adds meaningful semantics beyond the schema: it clarifies that `project_id: null` returns ONLY Knowledge Base files while omitting the field spans everything, and that `kind` narrows to one content class. This elevates it above the baseline, though the remaining parameters are straightforward.

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 ('List file metadata') and enumerates the exact filtering dimensions. It explicitly contrasts itself with sibling tools (`files.search`, `projects.map`) by naming them and their distinct use cases, making it unambiguous which tool an agent should pick.

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 browse known structure') and names the two key alternatives with their conditions (`files.search` for keyword/content lookup, `projects.map` for a denser whole-vault dump). It also clarifies the subtle `project_id: null` vs omit distinction, which is crucial for correct invocation.

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

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

Since annotations are absent, the description carries the full burden, and it does well: it discloses the operation is local, requires no auth, and has no limits, which is unusual and helpful context. It also implies a destructive/renaming action but doesn't explicitly state whether the original is removed or if it's reversible; however, given the detail that does exist, it's a strong disclosure. It could improve by stating whether the move is reversible, but the existing information is substantial.

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 the primary purpose and the key constraint front-loaded. The alternative usage is clearly separated, and every word contributes meaning. It's efficient and scannable for an agent.

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 complexity (3 params, one enum, one optional), the description covers the critical constraints (absolute path, containment, rejection of cross-project) and the alternative mode. It also mentions local operation and no auth/limits. With no output schema, an agent might want to know what the response contains (e.g., success/failure), but that's a minor gap. The essential behavioral guidance is present, so it's nearly 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?

The schema provides 100% coverage with descriptions for each parameter, including the enum and the interaction between 'kind' and 'new_path'. Since the schema already explains 'kind' and the relationship, the description adds minimal extra value—it essentially repeats the constraint. The baseline is 3 due to high coverage, and the description doesn't exceed that by adding new meaning beyond what's 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 clearly states it moves or renames a file, specifying the exact resource (file) and the action. It distinguishes this from other file operations by detailing the constraints and the alternative behavior with 'kind', which differentiates it from siblings like files.delete or files.update. The scope (must be inside owning project or global knowledge directory) 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?

It provides explicit conditions for use: the destination must be absolute and inside the project or knowledge directory, and cross-project moves are rejected. It also clearly explains the alternative usage pattern (using 'kind' instead of 'new_path') and what that does, effectively telling an agent when to use this tool vs. when to use a different approach. It even hints at avoiding misuse by flagging cross-project moves.

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 carries full responsibility – and it delivers: it declares read-only semantics, no side effects, auth, or rate limits, explains batch error isolation ('per-ID failures isolated, batch never partial-throws'), and gives per-mode response shapes.

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?

A dense but efficiently structured description that front-loads the purpose and modes, then uses semicolons to compactly convey constraints and response shapes. No filler; every clause carries operational 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 tool with 5 parameters, multiple interacting modes, no annotations, and no output schema, the description covers all decision points: which id/path/ids to pass, how to combine section/lines, what responses look like, and how errors behave. The only omission is the exact structure of tags/est_tokens, but that's minor.

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

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

Although the input schema already documents every parameter, the description adds combinatory semantics not in the schema: exactly-one-of requirement, mutual exclusion of section/lines, validity restricted to id, and response-shape implications per mode. This is additive value beyond structured fields.

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

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

States a specific verb ('Read') on a specific resource (files) and enumerates the five access modes. Explicitly contrasts with files.describe for inspection, so an agent can distinguish it from the sibling that shares the 'files' domain.

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 identifies when to prefer an alternative ('Prefer files.describe to inspect without paying body tokens') and structures usage by mode. The mutual-exclusion and requirement rules tell the agent exactly which parameter combination to assemble.

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

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

Annotations are empty, so the description carries the full burden, and it delivers: 'Read-only; no side effects, auth, or rate limits' covers the safety/permission profile. It also adds the counterintuitive empty-outline behavior ('file has no markdown headings — it may still have content'), preventing an agent from misreading an empty result.

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 compact sentences: purpose, safety, usage-as-probe, and empty-outline fallback. Every sentence carries a distinct, necessary fact, and the most important information is front-loaded in the first clause.

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

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

Despite having no output schema, the untouched return shape is named inline (level, text, line, byteStart, byteEnd) and the empty case is massively covered. The only gap is error handling for invalid file ids, but for a single-parameter, side-effect-free probe the description is substantially 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?

The single parameter file_id has 100% schema description coverage ('File ID'), so the description adds nothing meaningfully new about the parameter itself. The text references the logical file and headings, but this is the baseline-3 for schemas that already fully document parameters.

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

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

The description opens with 'Return a flat list of markdown headings for one file (level, text, line, byteStart, byteEnd)', which names the verb, resource, and output shape. It clearly distinguishes from siblings like files.read (full body) and files.list (multiple files) without needing to open the 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?

'Use as a cheap probe before files.read({ id, section }) or files.update(...)' names the exact sibling alternates and the cost rationale. The empty-outline note also tells the agent to fall back to files.read in full or with lines, making the when-to-use and when-to-bail behavior explicit.

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 that the tool is read-only with no side effects, auth, or rate limits. It also discloses the caps on results (500 files / 10 hits per file in multi-file mode, 100 hits default in single-file mode) and the error behavior for invalid regex. It could also mention that single-file mode changes the response shape, which it does. This is thorough, though not perfect—perhaps missing details on performance impact or response format, but sufficient.

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 front-loaded with the core purpose. It uses three paragraphs that flow logically: the main function and when to use it, the single-file mode variant, and caps/behavioral details. Every sentence adds value, and there is no redundancy. The key caveats (slower than FTS, response shape change, caps) are placed prominently. This is a model of concise yet comprehensive tool description.

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

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

Given the tool's complexity (8 parameters, two modes, multiple caps, error behavior), the description is remarkably complete. It covers the default behavior, the single-file mode, parameter interactions, caps, and error handling. Since there is no output schema, the description explains the response shape change for single-file mode. The only minor omission is a more detailed description of the multi-file response shape, but the description hints at per-file hits with line numbers. Overall, nothing critical is missing for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents each parameter with details like 'Ignored when file_id is set' and 'Default false'. The description adds value by clarifying the modes and the interaction between parameters (e.g., `project_id`/`kind` ignored when `file_id` is set, `max_matches` only used in single-file mode). However, it doesn't provide additional semantics beyond what's in the schema, but the baseline is 3 because the schema is thorough, and the description reinforces it.

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: matches a JS regex against file bodies, with a clear distinction between multi-file and single-file modes. It names the sibling `files.search` and explains when to use this tool instead. It could be stronger by explicitly stating that it is a regex search tool, but the verb 'Match' and resource 'file bodies' are specific enough.

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 versus the FTS `files.search`, emphasizing that regex search is slower and should only be used when FTS misses substrings, URLs, or code identifiers. It also explains the two modes (default multi-file and single-file with `file_id`), and notes that `project_id`/`kind` are ignored in single-file mode. This is comprehensive and leaves no ambiguity.

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 it excels. It discloses that the operation is destructive, that current uncommitted content may be lost, that the file watcher might pick up the change early, that there are no external auth or rate limits, and that it re-indexes FTS.

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 covers warning, operation, side effects, data loss, auth, return shape, and usage. Each sentence earns its place, and the 'DESTRUCTIVE.' warning is front-loaded for immediate risk awareness.

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 is complete enough for safe invocation: it names the return fields, documents the destructive side effect, specifies the source of the hash, and warns about watcher behavior. Nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value beyond the schema by explaining the hash must come from THIS file's get_history and that foreign hashes throw, as well as the data-loss consequence of supplying a hash. This justifies a score above baseline without redundancy.

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: overwrite a file's on-disk content with a version from a git commit, then re-index FTS. It closes by carving out the intended use cases (undo accidental edits, recover a known-good version), which clearly distinguishes it from sibling file tools like files.update or files.delete.

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 says explicitly when to use this tool ('Use only to undo accidental edits or recover a known-good version') and adds a hard prerequisite: the hash MUST come from files.get_history for THIS file and foreign hashes throw. This provides an actionable and unambiguous gate, even without naming a specific alternative sibling.

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

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

With no annotations, the description carries full burden. It discloses read-only nature, no side effects, auth, or rate limits; explains ordering (dictionary-wins then BM25); describes token budget capping and skipped files; and notes FTS tokenization limitations. This is thorough and honest.

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?

Although dense, every sentence contributes critical information. Key facts are front-loaded (default behavior and main mode), followed by alternatives and edge cases. No fluff or repetition; the length is 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?

The description fully covers all 8 parameters, explains the two output shapes (match list vs bundle with meta), describes the return fields and ordering, and provides limitations and fallbacks. Given no output schema, it is remarkably complete for an agent to call it correctly.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: include_bodies changes response shape, format has a default and is ignored otherwise, max_tokens governs the ranking-based cutoff, project_id null vs omit semantics, and tags require all match. This greatly assists 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 performs full-text keyword search across files, and distinguishes it from sibling files.regex_search by noting FTS limitations. It also explains the two modes (default match list vs include_bodies bundle), so an agent knows exactly what it 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?

Provides explicit guidance: use include_bodies instead of files.search + N×files.read for multiple related files as one context blob, and fall back to files.regex_search for URLs, hyphenated terms, and partial substrings. This leaves no ambiguity about when 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 the full burden, and it delivers: it discloses disk write and FTS5 re-index side effects, case-insensitive exact-string matching after trim, preservation of the heading line and siblings, error behavior for missing headings, local operation with no auth or rate limits, and the return value. 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?

The description is dense but every sentence earns its place: main behavior, default mode, section mode, error condition, operational context, and return value are all covered without fluff. The key behavior is front-loaded, and the alternative-mode guidance appears immediately after the default behavior.

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 complete for a file-update tool: it specifies inputs, modes, error cases, side effects, operational constraints, and the return shape (updated metadata with token counts). There is no output schema, so the description's explicit mention of the return value fills that gap. Nothing essential 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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema. It explains that `content` becomes the entire file by default but only the heading's body when `section` is set, and it details matching semantics and preservation behavior for `section`. This goes well beyond the baseline already covered by parameter 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 'Rewrite a file,' a specific verb and resource that clearly indicates modification of an existing file. It distinguishes two modes — full-body replacement versus partial section rewrite — and explicitly notes that the section mode does not create new sections, which differentiates it from files.create and other file operations.

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

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

The description gives explicit guidance on when to use section mode ('saves context budget vs resending the whole file') and when not to use it ('Throws if section is set but the heading doesn't exist... will NOT create a new section'). It also directs the agent to append via a full-body update first, which is a clear alternative path. This is strong usage direction.

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 idempotency, rejection cases (empty names, null bytes, leading separators, '..'), side effects (mkdir on disk, no DB rows until a file lands), and absence of external auth/rate limits. This is exemplary behavioral disclosure beyond the schema.

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

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

The description is dense but well-structured: it front-loads the core action, then idempotency, then rejection rules, then side effects, then auth/rate limits, then return value. Every sentence earns its place, and the structure is logical for an agent scanning for constraints.

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

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

For a 2-parameter tool with no output schema, the description is complete: it covers behavior, constraints, side effects, and return shape. An agent has everything needed to call it correctly and predict outcomes.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining that 'name' supports nested paths and that 'project_id' can be null/omitted for KB, which reinforces the schema. It doesn't add new syntax details beyond the schema, but the schema already covers the parameters well.

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 ('Create') and resource ('a folder under a project root or the KB'), and distinguishes it from siblings like folders.delete and files.create by clarifying it creates folders, not files. It also specifies the two locations (project root or KB), which is precise.

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 it: to create a folder under a project root or KB, with idempotent behavior and nested path support. It doesn't explicitly name alternatives or exclusions, but the context is strong enough for an agent to select it over siblings like files.create or folders.delete.

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 carries full burden. It clearly discloses destructuring behavior (recursive, disk+FTS rows), refusal behavior when project_id is passed, the non-recoverable nature after the call (except git backup if configured), and the response format ('Returns {success: true}'). It also notes no external auth or rate limits. This is comprehensive for a destructive 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?

Four sentences, all substantive: destructive scope, refusal condition and reason, validation reference and recoverability, and response format. Front-loads the critical destructive warning. No filler, each 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 complexity (destructive recursive delete with refusal logic) and lack of annotations, the description covers all needed operational knowledge: preconditions (name validation), special cases (project_id), consequences (non-recoverable), and return value. Output schema is absent, but the description specifies the return shape, completing the 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?

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying project_id's effect ('Project IDs are rejected' and refusal rationale), which the schema only hints as 'rejected'. It also confirms name validation parity with folders.create, helpful for expected format. This elevates 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 opens with 'DESTRUCTIVE — recursively delete a folder under the KB AND every file inside it (disk + FTS rows)', clearly stating the verb (delete), resource (folder), and full scope (recursive, disk and FTS rows). It distinguishes from sibling tools like files.delete, which lacks folder recursion, and from folders.create, which it references for shared validation. This specificity prevents selection confusion.

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 NOT to use: when project_id is supplied, the tool refuses to avoid racing the file watcher, and recommends removing project content via the editor instead. It also references folders.create for same name validation, implying usage contexts match that tool's naming rules. This gives clear do/don't guidance with an alternative path.

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. It explicitly states read-only, no side effects, auth, or rate limits, and discloses the throw condition for unknown project_id. It also describes the return format (relative paths). This is thorough and goes beyond typical.

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 well-structured sentences: first states purpose and output, second covers behavior and usage guidance. No wasted words, and the key distinction (relative paths) is front-loaded.

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

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

For a single-parameter read-only tool with no output schema, the description fully explains what it returns, when to use it, and its edge cases. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and the schema already describes the parameter ('Pass null or omit to list KB folders'). The description adds the throw condition for unknown project_id, which is behavioral rather than semantic. Baseline 3 applies because schema handles the 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?

States a specific verb and resource ('List folder paths') with explicit scoping (project root or Knowledge Base), and distinguishes from sibling tools like folders.create and files.create. The output shape is also given, so the purpose is unambiguous.

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

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

Explicitly says when to use this tool (discover where to drop a new file via files.create's folder argument, navigate vault structure) and when not to (use folders.create to actually create a folder). Names the relevant sibling and the condition that selects 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 and does so thoroughly: it discloses potentially destructive side effects, 60-second token expiry, non-reusability, token-as-auth, absence of rate limits, and the inert text response for invalid/expired/consumed tokens.

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

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

The description is dense but well-organised: purpose first, then the safety warning, expiry/reuse constraints, auth model, and failure behavior. Every clause adds value; the only cost is length, which is justified for a destructive execution tool.

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 one-parameter tool with no annotations and no output schema, this covers authentication, expiration, failure behavior, and side effects. The only real gap is that it never explicitly states what a successful confirmation returns, relying on the reader to infer the underlying Hand's output.

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 already labels the token. The description adds meaningful semantics beyond that: single-use, 60-second lifetime, and returned by any confirm-required Hands tool. This deepens the agent's understanding of the parameter without changing its syntax.

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

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

States a specific action (approve and execute), a precise resource (a previously-issued Hands invocation), and the key constraint (single-use approval token). This clearly distinguishes it from informational sibling tools like hands.list or hands.reload.

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

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

Explicitly says the tool should only be called when the user has authorised the pending action, which doubles as a when-not. It also explains exactly where the token comes from and that confirm-required tools issue it, giving the agent the full triggering context.

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

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

With no annotations provided, the description fully carries the behavioral burden. It explicitly states 'Read-only; no side effects, auth, or rate limits' and clarifies that the schema mode is a static document 'unrelated to any specific registered hand'. This gives an agent reliable expectations about safety and scope without needing annotations.

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

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

The description is well-structured and front-loaded: the core purpose appears in the first sentence, followed by context, mode explanation, safety guarantee, and usage guidance. Every sentence earns its place with no redundant 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?

For a tool with one optional parameter and no output schema, the description covers everything an agent needs: what the default output contains, what the schema mode contains, the registered-at-load-time context, safety profile, and the appropriate use cases. Nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful parameter semantics beyond the schema: it explains what `schema: true` returns (complete authoring reference with validation rules, security guarantees, limitations, annotated example) and clarifies it is static and unrelated to registered hands. This exceeds the schema's simple boolean explanation.

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 precise verb and resource: 'List every Hands command tool currently registered', followed by the exact output fields (project scope, tool name, danger level, confirmation flag, description). It clearly distinguishes the default mode from the `schema: true` mode and is distinct from siblings like `hands.reload` and `hands.confirm`.

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 each mode: default list mode for discovering permitted side-effectful project commands, and `schema: true` when helping a user write or fix a `kontexta.json`. It also names the sibling `hands.reload` as the follow-up action after editing, providing clear routing among 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?

No annotations are present, so the description carries the full burden. It explicitly discloses the side effect scope ('running MCP session's tool inventory only'), declares idempotency, notes no disk writes, and rules out external auth/rate limits. It also states return contents.

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?

Description is information-dense but every sentence adds value: primary effect, side-effect scope, idempotency, auth/rate limits, return values, and usage guidance. The structure is front-loaded with the main action and consequences, followed by supporting 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?

For a zero-parameter tool with no annotations and no output schema, this description is complete. It tells the agent what will happen, what will not happen, when to invoke it, what it returns, and where to find related schema. Nothing essential 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 tool has zero parameters and the schema already reflects that with an empty properties object. The description adds 'Takes no parameters,' reinforcing the schema. Baseline for zero parameters is 4, and no further parameter documentation 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?

Description states an explicit action ('Re-scan every registered project's kontexta.json and rebuild the live Hands tool registry') and the observable consequences (new tools callable, removed tools disappear from tools/list). This clearly distinguishes it from sibling tools like hands.list and hands.confirm.

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?

Description gives explicit trigger condition: 'Use after editing a kontexta.json mid-session.' It also points to hands.list({ schema: true }) for schema details, effectively providing an alternative lookup path. This is precise and 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 provided, the description carries the burden. It states the effect (updates journal_meta.status_latest) but does not disclose side effects, idempotency, failure behavior, or authorization needs. It adds some behavioral context but lacks depth.

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, two sentences, with the core action and its effect front-loaded. Every sentence earns its place, and there is 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?

The tool is simple with one parameter and no output schema, so the description doesn't need to explain return values. However, it lacks details on error handling (e.g., what happens if a slug is invalid?) and confirmation messages, which an agent might need for robust 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 schema already fully documents task_slugs with a description. The description adds the context that these slulgs should be for entries upgraded, but does not add syntax or format details. With 100% schema coverage, baseline is 3, and the description's contextual hint pushes 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 clearly states that this tool commits upgrades to mechanical journal entries, marking status_latest. It specifies the action (commit) and the resource (journal entries), and is distinct from siblings like journal.append and journal.distill. However, it does not fully differentiate from journal.housekeep or 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 description explicitly says to call this 'after dispatching subagents to upgrade mechanical journal entries to LLM-narrative', which gives clear context. It does not mention alternatives or when not to use it, but the workflow context is sufficient.

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 bears the full burden of behavioral disclosure. It reveals important side effects: advancing high-water mark, writing markdown entries, and auto-provisioning project rows for orphan slugs, plus the crucial 'Idempotent' guarantee. It does not cover failure modes or effects on existing entries, but is notably transparent for a mutation 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 sentences with zero filler: the first lists pipeline steps in a compact colon-delimited series, the second is a one-word idempotency note, and the third explains the auto-provisioning edge case. The action is front-loaded and 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?

For a tool with 2 optional parameters, no output schema, and no annotations, this description is quite complete: it conveys the pipeline flow, state advancement, idempotency, and an edge-case side effect. It does not describe the return value or error conditions, but it is sufficient for an agent to 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 parameters have meaningful descriptions, including max_events' default/max/exclusiveMinimum and project_slug's default to current active project. The description adds no parameter-specific meaning beyond the schema, 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 verb and resource ('Run the distillation pipeline') and enumerates the exact operations: read events since high-water mark, group by topic, write mechanical markdown entries, advance high-water. This distinguishes it clearly from sibling journal tools like append, note, or 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?

Usage is implied rather than explicit: the description explains what the pipeline does and mentions idempotency and auto-provisioning, but it never states when to use this tool versus sibling journal tools or under what conditions one would run it. No alternatives or exclusions are 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 behavioral burden. It discloses that the operation is idempotent and that it prunes/archives specific data (raw .jsonl files and cold tasks), which is meaningful beyond the tool name. It could mention whether pruning is reversible or requires permissions, but the core destructive/archival behavior is surfaced.

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 compact sentences front-load the main action and essential behavioral detail. No filler or repetition. Every word adds information, making it 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?

For a low-complexity tool with one optional parameter and no output schema, the description covers the action, idempotency, what data is affected, and the governing policy. It does not describe return behavior, but this is a housekeeping action where the core invocation semantics are sufficiently 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?

The sole parameter, project_slug, is fully documented in the input schema with 100% schema description coverage. The description adds no extra parameter-level detail, but the schema already explains the parameter's meaning and default, 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 clearly names the operation ('Run journal retention/archival for a project') and gives concrete scope with 'Prunes old raw .jsonl files and archives cold tasks per the configured retention policy.' This is specific and distinguishes it from journal editing/appending siblings like journal.append or journal.note.

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 establishes clear context for when to use the tool: to run journal retention/archival according to the retention policy. It does not explicitly name alternative tools or state when not to use it, so it stops short of a 5, but the context is unambiguous enough for an agent to route correctly.

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 says 'Report' which hints at a read-only operation, but it does not explicitly state that it has no side effects or what happens on invalid input. There is no mention of permissions or the meaning of 'high-water mark,' leaving important behavioral aspects unexplained.

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, concise sentence that front-loads the core action ('Report') and includes the key resource. It contains no fluff, though it could potentially elaborate on the return format without losing brevity. It is efficient and well-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?

For a tool with no output schema and no annotations, the description should provide more context about the report's content and behavior. It does not explain what the backlog and high-water mark represent, what the response looks like, or whether the operation is purely read-only. This leaves gaps that an agent would need to infer or test.

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

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

Schema description coverage is 100%, and the only parameter project_slug is adequately described in the schema ('Project slug to check. Defaults to the current active project.'). The description does not add additional semantics beyond what the schema provides, so a baseline 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 clearly states the verb 'Report' and the specific resource 'journal backlog and high-water mark' for a project. It distinguishes itself from sibling journal tools (append, commit_upgrades, housekeep, note, etc.) by its reporting nature, leaving no ambiguity about what it 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 implies usage as a status/information retrieval tool, but it does not explicitly mention when to use it over alternatives or any exclusions. Since it is a simple report, the context is reasonably clear, but no explicit guidance on when to avoid it is provided.

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 behavioral burden. It discloses side effects (creates the journal file if missing), idempotency (same file_id per calendar day), storage semantics (agent_note event in Layer 1 for notes), and return values for every kind. This is thorough for a mutation tool, covering both effects and results.

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. It opens with the core purpose, then uses a clear kind-by-kind breakdown with inline return types. While slightly long, every sentence carries actionable information, and the structure mirrors the enum options, aiding comprehension. 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 no output schema, the description must specify return values, and it does for each kind: {file_id} for append, {ok, recorded_at} for note and intent. It also covers creation behavior, daily idempotency, and how notes surface in distillation. With 5 parameters and 3 conditional modes, this is a complete operational spec for an agent to call 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 substantial semantic value: it explains the meaning of each kind, which fields are required conditionally, and the behavioral consequences of each choice. For instance, it clarifies that 'intent' needs 'summary' while 'append'/'note' need 'text', and explains how 'intent' affects distillation. This goes well beyond the schema's generic field 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 precise verb and resource: 'Write one event to the current project's journal.' It then enumerates three distinct kinds (append, note, intent) with concrete behaviors and return payloads. This clearly differentiates it from sibling journal tools like journal.distill or journal.status, which are read/aggregation operations, and from files.write, which targets a different storage layer.

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 for each kind, e.g., 'use when the user redirects what you're working on' for intent, and specifies conditional required fields. It does not explicitly state when not to use this tool versus alternatives, but the sibling set makes the write purpose obvious, and the kind-specific instructions are 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 behavioral burden and succeeds: it declares 'Read-only; no side effects, auth, or rate limits' and explains the derived has_hands flag semantics. This goes well beyond a simple operation summary.

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 tightly organized: the core behavior and output fields come first, then behavioral guarantees, then usage guidance, then alternatives. Every sentence adds distinct 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?

For a parameterless list tool, the description is fully sufficient: it lists the returned fields, defines the only non-obvious flag, states the operation's safety profile, and explains how to use the result with scoped tools. Nothing needed for correct invocation is missing.

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

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

The tool has zero parameters, so there are no parameter semantics to clarify. The description appropriately focuses on output fields instead, which is useful given there is no output schema; baseline for zero-parameter tools is 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 and resource: 'List every registered project with id, name, absolute path, and a derived has_hands flag.' It clearly differentiates from related siblings like projects.register and hands.list by stating what this tool is and is not.

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 usage guidance is provided: 'Use to find the project_id to pass to scoped tools' with concrete examples. It also names alternatives for adjacent actions—'To register a new project use projects.register; to inspect its Hands tools use hands.list'—making when-to-use and when-not-to-use 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?

No annotations are provided, so the description carries the full burden. It discloses read-only behavior, no side effects, no auth, no rate limits, the max_lines cap, the est_tokens and warning fields, and the defaults for include_tags and show_titles. This is rich behavioral context. It doesn't describe the exact output format beyond 'compact indented outline', but the description covers the key behavioral traits an agent needs to know.

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

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

The description is dense but every sentence earns its place: purpose, token savings, read-only safety, cap/warning behavior, project_id semantics, defaults, and usage guidance. It is front-loaded with the core purpose and scoping, and the usage guidance is at the end. 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 read-only outline tool with 4 optional parameters, all documented in the schema, and no output schema, the description covers the essential context: what it returns, how it behaves, its limits, and when to use it. The only minor gap is the exact output format, but the description's 'compact indented outline' plus the schema's parameter descriptions are sufficient for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds context for project_id (null = KB only, omit = everything) and mentions defaults for include_tags and show_titles, which slightly exceeds the schema. However, the schema already covers these, so the description adds marginal value. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Return'), a specific resource ('compact indented outline of folders, file titles, tags, and IDs'), and a clear scope ('single dense block'). It also distinguishes itself from files.list by noting the token savings, and from files.search by noting the orientation use case. This is a clear, specific purpose that an agent can act on.

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 when to use it: 'Use to orient yourself in an unfamiliar vault or project; for keyword lookup use files.search.' It also explains the project_id semantics (null = KB only, omit = everything), which is a usage guideline. This is explicit when/when-not guidance with a named alternative.

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 present, the description carries the full burden and fully delivers: it discloses write/delete effects, explicitly calls the prune 'destructive on stale index rows' while clarifying files on disk are never deleted, notes idempotency, skip rules (>5MB, junk dirs), and absence of auth/rate limits. No important side effect is hidden.

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: scope explanation, side effects, idempotency, limits, return shape, and usage trigger. Despite being longer than typical descriptions, it is densely packed with non-redundant information and front-loads the primary 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?

This is a side-effectful tool with two modes, yet the description covers all needed context: what it reconciles, what it writes/deletes, what it skips, return shape, and when to use it. Even without an output schema, the agent knows exactly what to expect and how to invoke this correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the behavioral difference between project_id set (re-runs discoverFiles) and null/omitted (walks knowledge/, prunes stale rows), which goes beyond the schema's generic 'Pass null or omit' phrasing.

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 pair: 'Reconcile the FTS index against disk.' It then partitions the behavior by project vs KB scope, making the tool's dual-mode purpose explicit and distinguishing it from siblings like files.diff_against_disk and files.search.

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

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

Ends with explicit usage guidance: 'Use after editing files outside Kontexta, or when files.diff_against_disk reports drift.' This directly tells the agent when to invoke it and ties it to a sibling tool's signal, making the trigger condition 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?

No annotations are provided, so the description carries the full burden, and it does so thoroughly. It discloses side effects (writing metadata to disk, recursive markdown scan, Hands tool registration), idempotence, local-only operation, and the distinction between fatal errors and non-fatal warnings.

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 organized with clear sections (SIDE EFFECTS, AUTH/RATE, PARAMETERS, RETURNS, ERROR CONDITIONS) and front-loaded purpose. It is on the longer side, but each section contributes necessary behavioral or usage detail for a complex operation.

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, the absence of an output schema, and no annotations, this description is remarkably complete. It documents the full return payload, error conditions, idempotency, side effects, and parameter guidance, giving an agent everything needed to invoke the tool correctly 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?

Even with 100% schema description coverage, the description adds substantial value beyond the schema: it defines 'path' as required with the strong DO NOT guess directive and instructs the agent to ask the user for the absolute path when only a name is provided. It also clarifies the meaning of 'name' and 'description' with practical context and describes the failure mode for an unresolvable path.

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: 'Register a new project and link it to the Kontexta knowledge system.' This clearly differentiates it from sibling tools like projects.list and projects.refresh_index. No ambiguity remains about what the tool accomplishes.

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

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

The description gives clear context for when to call it and includes explicit guidance about not guessing paths and asking the user for an absolute path. It stops short of explicitly comparing against sibling tools or stating when not to use it, but the use case is unambiguous enough that alternatives are not needed.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It discloses the return shape, the critical src-vs-url resolution difference between dashboard and export, and that bytes must be base64-encoded. It does not mention overwrite behavior, size limits, or permission requirements, but for a simple write tool the key behavioral caveats are present.

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, all dense with necessary information: what the tool does, what it returns, how to use the return value correctly, and a critical pitfall to avoid. No filler or repetition of schema fields beyond what adds value.

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

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

For a simple two-parameter tool with no output schema, the description is complete: it covers the action, target location, input encoding, return shape, and correct/incorrect usage in the consuming context. An agent has everything needed to invoke it correctly and use the result properly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful value beyond the schema by explicitly stating that bytes are base64-encoded and by showing how the returned src should be used in HTML, which clarifies the practical role of the filename and bytes parameters.

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: 'Write an image or other binary resource into the shared reports/resources/ folder.' This clearly distinguishes the tool from sibling file/resource tools by naming the exact target folder and resource type. The report-embedding context further clarifies its unique role among the resources.* siblings.

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

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

The description gives clear context for use: adding binary resources to reports and embedding them via <img>/<a> tags with src. It also warns not to use url in report HTML. However, it does not explicitly state when to prefer this over files.create or other sibling tools, though the shared reports/resources/ folder implies the distinction.

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 side-effectfulness, creation of a new file, non-idempotency/no de-dup, auth defaults, upstream throttling risk, the AUTH_REQUIRED error shape, and the return payload. This is unusually 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?

Though long, every sentence carries critical operational information: side effects, idempotency, auth behavior, rate limiting, error handling, and return format. The SIDE-EFFECTFUL warning is front-loaded, and there is no filler or redundant phrasing.

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

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

Given the absence of an output schema and annotations, the description is remarkably complete. It explains what the tool does, what side effects occur, how auth works, what errors look like, and what the response contains. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents `url`, `title`, and `headers`. The description adds some context around `headers` for auth and mentions the title override default, but it mostly reinforces what the schema already states rather than adding substantial new semantics.

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: "fetches an EXTERNAL URL and writes a NEW KB file," and clearly differentiates this from sibling tools by explaining the exact pipeline (Readability extraction, markdown conversion, saving under `knowledge/urlclips/`). An agent can immediately tell this is an external-ingestion tool distinct from files.create or resources.add_report.

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 by ending with "Use to ingest external docs into the KB" and explains when to pass `headers` for auth-walled pages. It does not explicitly name alternatives or state when NOT to use this tool, but the use case is well-defined.

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 carries the burden. It discloses a key behavioral trait: the operation is a no-op if the file does not exist, which is valuable for an agent. However, it does not mention permissions, reversibility, or any other side effects. This is adequate but not exhaustive for a destructive operation.

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

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

The description is two sentences with no extraneous words. The primary action and scope are front-loaded, followed by the essential no-op behavior. Every word earns its place.

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

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

For a simple tool with one parameter, no output schema, and clear scoping, the description provides sufficient information for an agent to invoke it correctly. It covers the action, the target directory, and the no-op behavior. Nothing critical is missing for this level of 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 input schema provides full coverage (100%) for the single parameter, describing it as a relative filename. The tool description adds no extra detail about the parameter, so it does not enhance what the schema already conveys. Baseline 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 states a specific verb (delete) and a clearly scoped resource (files in reports/resources/). This distinguishes it from sibling tools like resources.add_report, resources.list_reports, and resources.export_report, as well as the generic files.delete. The purpose is 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 implies the tool is for deleting files within the reports/resources/ directory but does not explicitly state when to prefer it over files.delete or other alternatives. The scope is clear from the wording, but no direct guidance on alternatives or exclusions is provided.

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 disclosure burden. It transparently reveals return shapes ({url} vs {bytes_base64}), the authentication prerequisite, packaging differences (full CLI vs standalone kontexta-mcp), and the fallback behavior. This goes well beyond the structured schema fields.

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

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

The description is two sentences with front-loaded purpose. Every clause earns its place: main verb/resource, default return, authentication, alternative mode, availability caveat, and fallback. 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?

Given the tool has no output schema and no annotations, the description is complete for operational use: it specifies how to get each return type, the auth requirement, and packaging constraints. An agent knows what to expect and how to adapt its call. No critical information is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains the default output mode, the condition under which inline_bytes=true actually works, and the fallback behavior. This enriches understanding of the inline_bytes and id parameters without duplicating schema text.

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 ('Export') with a specific resource ('existing HTML report') and the output formats (PDF or PNG). It clearly distinguishes this from sibling resources.* tools (add_report, list_reports, delete_report) by describing the operation rather than management 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?

While it does not explicitly name alternatives or when-not-to-use, it provides clear context: it states the default behavior, the authentication requirement, and when inline_bytes is available (full kontexta CLI) vs when it falls back. This is sufficient contextual guidance for selecting and invoking the tool, though a direct contrast with sibling tools would be stronger.

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 present, the description carries the full burden of disclosing behavior. It clearly states what the tool does ('List all files currently stored under reports/resources/') and what it returns (filename, size, served URL), which is transparent for a read-only enumeration operation. It does not explicitly state that it is non-mutating, but 'List' strongly implies that, and no other side effects are suggested.

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 that states the action, the exact scope, and the return fields. Every word earns its place; there is no filler or repetition of the tool name.

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 is a zero-parameter, read-only listing tool with no output schemaasi, but the description covers both input scope and expected return values. Given the low complexity, there is no missing information that an agent needs in order to call it correctly.

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

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

The tool has zero parameters, and the schema coverage is effectively 100% since the schema declares no properties. With 0 params, the baseline is 4. The description adds no parameter syntax, and none is needed for this stateless list operation.

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 ('List') with an exact resource path ('all files currently stored under reports/resources/'), making the tool's scope unambiguous. It also names the return fields (filename, size, served URL), which helps distinguish it from generic files.list and from report management tools like resources.add_report or resources.delete_report.

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 this tool is used when enumerating files already stored under reports/resources/, but it provides no explicit when-to-use guidance or alternatives. There is no mention of when to prefer files.list or resources.export_report instead, so the usage context is only inferred from the resource path.

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 available, the description fully discloses behavior: additive (preserves existing tags), idempotent per tag, auto-creates rows in global table, persists to SQLite, no auth/rate limits, returns {success:true}, and throws on unknown file_id. This exceeds the burden placed on a description when annotations are absent.

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?

Description is front-loaded with the core action, then efficiency details, then persistence, then outcome/errors, then usage alternatives. Every sentence adds unique value with no redundancy; length is appropriate 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 only 2 parameters and no output schema, the description specifies the return payload ({success:true}) and error behavior (throws on unknown file_id). It also clarifies side-effects (auto-create, persistence) and environmental constraints (no auth/rate limits). Nothing necessary for correct invocation is missing.

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

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

Schema covers 100% of parameters (tags array and file_id), so baseline is 3. Description adds behavioral nuance (idempotency, auto-creation) but does not clarify the format or meaning of the parameters themselves beyond what the schema already states. It contributes modest value, but not enough to raise the score above 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?

Description states a specific verb ('Append') and resource ('tags to ONE file'), and immediately contrasts with siblings via 'To tag every file... use tags.search; to remove tags use tags.remove'. This makes the tool's purpose unmistakable and distinct from all 54 siblings.

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

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

Explicit usage guidance is provided: 'Use to label a single file' and exact alternatives for mass-tagging (tags.search) and removal (tags.remove). The instruction is direct and leaves no ambiguity about when this tool should be selected.

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 exist, so the description carries the full burden. It transparently states read-only nature, absence of side effects, auth, and rate limits, and explicitly warns that the result is not paginated (returns the entire taxonomy). This is exemplary disclosure for a tool with no 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?

Three concise sentences, front-loaded with the core action and result. Every sentence adds value: the first states what it does, the second covers behavioral guarantees and pagination, and the third gives usage scenarios and an alternative. 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 zero-parameter tool, the description is complete. It describes the output fields, the lack of pagination, the read-only behavior, and provides both use cases and a pointer to a sibling tool. There is no output schema, but the description compensates by listing the returned fields.

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 schema description coverage is trivially 100% (no parameters to document). Per calibration, baseline is 3. The description does not add parameter semantics because none exist, and it correctly implies a no-argument call by describing a simple list operation.

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 precise verb and resource ('List every tag in the global SQLite database') and enumerates the returned fields (id, name, applied count). It also implicitly distinguishes itself from siblings like tags.search and tags.suggest by stating it returns the entire taxonomy with no filters.

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 guidance is given: use it to discover existing labels before tagging to reuse rather than fork, and to find tag IDs for tags.remove. It also names an alternative (files.describe) for file-specific tags, providing both when-to-use and when-not-to-use conditions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals destructive scope ('on the link only'), idempotency, absence of external auth/rate limits, and the return value, providing unusually complete transparency for a mutation 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?

Every sentence earns its place: the core action is front-loaded, followed by destructive scope, idempotence, auth, return value, parameter reminder, and the alternative. Dense yet efficient 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 destructive-adjacent tool with no annotations and no output schema, the description is remarkably complete: it covers safety, reversibility, idempotence, return format, parameter sourcing, and alternative sibling behavior. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful value by emphasizing that tag_ids are integers, not names, and that file_id refers to a single file, resolving common misinterpretations 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 states a specific verb ('Detach') and resource ('tag IDs from ONE file'), immediately clarifying the operation's scope and distinguishing it from destructive file/tag deletion. It also explicitly differentiates from siblings like tags.add and tags.search in a later sentence.

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

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

The description gives explicit usage guidance: it clarifies that this tool removes tags from one file only, that IDs not names are required, and that bulk untagging by query is not available; it points to tags.search as the additive-only alternative. This leaves no ambiguity about when to choose this tool.

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

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

With no annotations present, the description takes full responsibility for behavioral disclosure. It explains side effects (additive, idempotent per tag), scopes of modification, per-file error isolation, lack of external auth/rate limits, absence of dry-run, and the exact return shape. This is exemplary.

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. The description front-loads the core action ('Bulk-tag'), then covers side effects, error handling, safety caveats, parameter nuance, and return format without 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 mutating tool with five parametersaint, no output schema, and no annotations, the description is remarkably complete. It explains the return fields, warns about the lack of dry-run, directs the agent to use files.search as a preflight, and clarifies filter semantics, leaving no critical gap 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%, so the baseline is 3. The description adds valuable parameter meaning beyond the schema: tags[] acts as an ALL-match filter scoping the search, not controlling which tags get added, and add_tags is applied to every matching file. This resolves ambiguity that the schema alone leaves open.

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: run an FTS search and append tags to every matching file. It frames the tool as 'Bulk-tag', which distinguishes it from sibling tags.add and files.search, and the resource (tag links on matching files) is explicit.

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 intended use case—bulk-tagging by query—is clearaski, and the no-dry-run warning explicitly instructs the agent to preflight with files.search. It does not formally enumerate alternatives like tags.add, but the bulk vs. single-tag distinction is strongly implied by the description and sibling context.

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