kontexta

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 flags side effects and network access, explains the auth model (local git credentials, no in-server auth), notes remote rate-limit potential, describes idempotency (no-op commit skipped but push still runs), and lists failure modes (missing repo, network/auth/conflict push failures).

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 critical side-effect warning, then moves efficiently through purpose, auth, idempotency, errors, return shape, and usage. Every sentence carries distinct, useful information 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?

Although there is no output schema, the description provides the return shape ({success, copied_files_count, copied_paths}), the auth model, failure conditions, and idempotency behavior. An agent has everything needed to invoke and interpret 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% for the single project_id parameter, so the schema already documents the parameter fully. The description adds no syntax or format detail beyond what the schema provides, making the baseline 3 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 specific verbs and resources: syncing KB data into a git backup directory, creating a commit, and pushing to origin. It is immediately distinguishable from sibling tools like journal_commit_upgrades or admin_refresh_session_context because it names the exact backup/git-push behavior.

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

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

It gives clear context for use: 'Use after a batch of KB writes to get changes off-machine.' This tells the agent when the tool is appropriate. However, it does not name alternatives or explicitly state when not to use it, so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full burden and does so well: it declares the operation read-only with no side effects, no auth requirement, and no rate limits, and it enumerates the return payload (existence status, full content, missing required sections, new-user hint). This is exactly the behavioral context an agent needs before calling a 0-parameter read 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 tight sentences, front-loaded with what the tool returns before the when-to-use guidance. Every sentence adds information, though the safety sentence ('Read-only; no side effects, auth, or rate limits') is slightly list-like and could be folded into the purpose statement.

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

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

With no output schema and no annotations, the description compensates by describing both the side-effect profile and the shape of the response, including the existence/missing-sections case. 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 tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly does not waste words on parameter 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?

States a specific verb and resource: 'Return the user profile stored in the Knowledge Base,' and clarifies what a profile contains (context, role, preferences, goals). The purpose is unambiguous, but it does not differentiate itself from nearby siblings such as admin_overview or admin_refresh_session_context, which an agent could plausibly confuse it with.

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 at session start to understand who you're working with' gives explicit timing and intent for invocation. It stops short of naming when NOT to use it or pointing to an alternative tool for related needs (e.g., admin_refresh_session_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, the description carries the full behavioral burden and does well: it discloses idempotency (fenced markers + version skip no-op writes), that this is a mutation of project config files, the mandatory user-consent requirement, and that hooks install conversation-capture tooling or return a docker command. It omits permission scope and failure/partial-write behavior, so not 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 purpose is front-loaded, followed by the idempotency trait and then the mandatory-consent warning, so the most important constraints come early. The RETURNS block is useful given no output schema, though confirm semantics are repeated in both description and schema, a minor 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?

This is a complex, 5-parameter mutating tool with no annotations and no output schema, so the description must do a lot. It covers consent, idempotency, mode conditions, and even an explicit RETURNS shape, leaving it nearly complete; only permission scope and edge-case failure handling are absent.

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 five parameters, and the baseline is 3. The description adds marginal framing (update mode defaults to recommendation.target_files; target_agent is ignored/required under stated conditions) but does not add syntax or value detail beyond the schema.

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

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

The description gives a specific verb and resource: 'Write or update the kontexta workflow rules block in a project's agent context file(s).' This is far more specific than the generic files_update sibling, so an agent can infer the distinct scope. It stops short of explicitly naming or contrasting a sibling alternative, so it lands at a strong 4 rather than 5.

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 mode-level guidance (update mode vs create mode, when files is empty, when target_agent is required) and a mandatory consent step, which implies correct usage. However, it never states when to choose this tool over files_update or admin_transfer_agent_context, so the guidance is implied rather than 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?

No annotations are provided, so the description carries the full burden, and it does: 'Read-only; no side effects, auth, or rate limits', a performance warning that include_token_total stat()s every file and is 'measurably slower on large vaults', a correctness caveat that hard-deleted files are NOT surfaced, and a throw-on-invalid-format behavior. This is materially beyond what a 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?

Front-loads the resource then branches by mode, and every sentence carries information (defaults, caveats, routing). It is dense with backtick-quoted identifiers and layered clauses, so it reads more like compact reference notes than clean prose, but there is little genuine 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?

With no annotations and no output schema, the description fully compensates: it names the returned fields per mode, the perf tradeoff of include_token_total, the whats_new deletion caveat, and the auth/rate-limit profile. 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 already 100%, so the baseline is 3, but the description adds real cross-parameter meaning: mode-dependent applicability of since/limit/include_tags/include_token_total, the ISO-8601 vs relative-duration accepted formats, and the null-vs-omit distinction for project_id. Slightly redundant on the since-required point already stated 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?

Starts with a precise noun for the resource ('Vault-state snapshot') and then enumerates the two modes and the exact fields each returns (file_count, untagged_count, top_tags, by_project). An agent can distinguish it from files_list, files_diff_against_disk, and other admin tools without opening any 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?

Gives explicit when-to-use for both modes ('cheap dashboard or spot untagged content for cleanup', 'use whats_new at session start to catch up') and names the alternative for the adjacent job (files_diff_against_disk for live disk-vs-index drift). Nothing is left to inference.

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

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

With no annotations, the description carries the full burden and does well: it declares 'Read-only; no side effects' and explains the return payload is the same block sent as MCP instructions at session start. It stops short of stating latency/cost or whether the re-read is cached, but the core safety and idempotency profile is 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?

Three sentences, front-loaded with the action, then the trigger, then the return/safety note. Slightly redundant phrasing ('as it stands NOW' plus 'current picture') but no wasted content.

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

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

No output schema exists, and the description compensates by naming the return block's contents. For a zero-param read tool, everything an agent needs to call it correctly is present; only freshness/caching semantics are left unspecified.

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

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

The tool takes zero parameters, so there is nothing to describe; baseline is 4. The description correctly does not invent parameters or imply filtering/config options that the empty schema does not support.

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 exactly what the context block contains (profile, upcoming events within 7d, conflicts, freshness nudge). This clearly distinguishes it from the session-start snapshot behavior and from sibling admin tools.

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

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

Explicitly names the trigger conditions ('user just edited their profile or added/moved calendar events') and the goal ('want the current picture instead of the snapshot taken at session start'). The alternative — doing nothing and using the stale snapshot — is implied and understandable.

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, so the description carries the full burden and does so thoroughly: it emphasizes COPY-only, guarantees no destructive filesystem operation, explains the response includes source paths for manual cleanup, flags the consent requirement, lists skip reasons, and states SHA-256 idempotency. This is exactly the behavioral context an agent needs 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?

Front-loaded with the core action, then layered guarantees, consent requirement, parameters, returns, and idempotency. Every section is labeled and earns its place, though it is on the longer side with some redundancy between the description and schema for confirm/project_id.

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

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

Despite no annotations and no output schema, the description fully describes return shape, skip reasons, and idempotent behavior, so an agent has everything needed to call it correctly. Complete for a consent-gated mutation 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, but the description adds value beyond the schema: it explains the omit-vs-empty-array default for files, the source of project_id, and the consent intent behind confirm. The added nuance about transfer-all semantics is the most useful contribution.

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 (COPY) and resource (agent context files: CLAUDE.md, AGENTS.md, .cursor/rules/*.mdc) plus the destination (Kontexta per-project knowledge base with FTS5 indexing and git-sync). An agent can instantly tell this apart from sibling admin tools like admin_commit_backup or admin_onboard_agent.

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 requires seeking user consent before calling and setting confirm:true only after agreement, and clarifies the default behavior (omit files to transfer all detected context files, same list as register_project/onboard_agent). It stops short of naming an explicit alternative tool or when-not-to-use condition, but the guidance is clear 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, the description carries the full burden and does well: it flags SIDE-EFFECTFUL, declares non-idempotency, and specifies that a duplicate name throws — exactly the failure mode an agent needs. It omits auth/permission requirements and whether the operation is reversible.

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 with the critical warning (SIDE-EFFECTFUL, not idempotent) front-loaded; no filler and every clause carries 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 4-param creation tool with no output schema, the description covers the essential: what it creates, the side effect, the duplicate-name failure, the return shape `{entity}`, and the follow-up call. Nothing needed to 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 description coverage is 100%, so all four parameters are already documented in the schema, making 3 the baseline. The description restates the case-insensitive uniqueness constraint on `name` rather than adding new semantic detail about `kind`, `notes`, or `timezone`.

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 ('Create a new tracked entity') and defines the concept with concrete examples (server, delivery van, store location, room) so an agent knows exactly what qualifies. It is clearly distinguishable from calendar_entities_update/delete/list/link siblings.

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

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

Explicitly routes the agent forward: 'Use `calendar_entities_link` afterwards to record dependencies for conflict detection.' This tells the agent the tool is a prerequisite step in a workflow, but it does not state when NOT to use it (e.g. when the entity already exists, or as an alternative to update).

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 does so well: it discloses irreversibility ('Permanently delete'), non-idempotency ('deleting an unknown id throws'), the cascade side effect on events and links, and the response payload. These are exactly the traits an agent needs to reason about before a destructive call.

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 sentences with zero waste; the destructive warning is front-loaded and capitalized so it cannot be skimmed past. Each subsequent sentence adds a distinct fact (cascade, idempotency, return shape, alternative) rather than repeating itself.

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?

There is no output schema, yet the description still specifies the return shape ({success, deleted_events, deleted_links}), which closes that gap. For a single-parameter destructive tool with no annotations, the only unaddressed area is authorization or permission requirements, a minor omission against otherwise thorough coverage.

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?

Only one parameter exists and the schema documents it at 100% coverage ('Entity id to delete.'), so the schema does the heavy lifting. The description reinforces which id is targeted and notes that unknown ids throw, adding a small amount of meaning beyond the schema, but does not specify id format or where ids come from.

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 ('Permanently delete an entity') and immediately scopes it with cascade semantics ('AND cascade-delete every event and link attached to it'). This clearly distinguishes it from calendar_events_delete and calendar_entities_update, which an agent can tell apart without opening any schema.

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

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

Explicitly names the alternative ('To deactivate without losing history, use `calendar_entities_update` with `active: false` instead') and the condition under which that alternative should be chosen. When-to-use and when-not-to-use are both present with no inference required.

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 zero annotations, the description carries the full burden and does so well: it flags 'SIDE-EFFECTFUL' up front, discloses idempotency ('upserts the label on repeat calls'), and explains the no-op removal case ('removing an absent link is a no-op'). It also documents return shapes ('Returns `{link}` or `{removed}`'), which is exactly the behavioral context an agent needs for a mutation with no 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?

Information-dense and front-loaded: the critical 'SIDE-EFFECTFUL' warning opens the text, and every subsequent clause adds distinct value (upsert, no-op, usage context, return shape). No padding 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 4-param mutation tool with no annotations and no output schema, the description supplies the mutation semantics, idempotency, no-op behavior, usage context, and return values. Nothing an agent needs to 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 description coverage is 100%, so the schema already documents from, to, label, and remove in detail. The description adds the 'A feeds B' example and the remove behavior, but this is marginal over the schema. Baseline 3 is appropriate when structured fields do the heavy lifting.

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

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

The description names a specific verb and resource: 'Create or update a directed dependency edge between two entities... or remove one.' It even gives a concrete example ('A feeds B'), so an agent immediately understands the operation. It stops short of explicitly distinguishing itself from entity-level siblings like calendar_entities_add/update, so it lands at 4 rather than 5.

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

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

It provides clear context for when the tool matters: 'Used by calendar_events_conflicts/calendar_events_list to flag overlaps across connected entities (one hop, either direction).' It also states the remove switch. However, it offers no explicit exclusions or comparison to the entity CRUD siblings, so no 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 provided, the description carries the full disclosure burden and does reasonably well: it declares read-only, no side effects, no auth requirement, and no rate limits, plus the return shape. It omits ordering, pagination, and what qualifies as a 'tracked' entity, but the safety/operational profile is unusually 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?

Three tightly packed clauses with zero filler: the safety profile leads, the operation follows, and the return contract closes. Everything 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 two-optional-parameter list tool with no output schema, the description supplies the missing return shape (`{entities, count}`) and the read-only guarantees, so an agent has enough to call it correctly. Minor gaps remain around ordering and pagination, which matter less for a small list endpoint.

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 'kind' and 'active_only' fully; the description adds no syntax, default, or semantics beyond that. Baseline 3 is correct when the schema does all the parameter work.

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 tracked entities') and adds a distinguishing detail: each entity is annotated with outgoing and incoming dependency links. That separates it from the sibling entity mutation tools (add/update/delete/link), though it never explicitly contrasts itself with calendar_events_list, which is the closest confusable list tool.

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 by 'List tracked entities' but there is no explicit when-to-use, when-not-to-use, or named alternative. An agent can infer it is the read counterpart to calendar_entities_add/update/delete, but nothing in the text routes it against calendar_events_list or the other *_list tools.

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

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

With no annotations, the description carries the full burden and does well: it flags SIDE-EFFECTFUL, states idempotency ('Idempotent per patch'), describes the soft-retire semantics of `active`, and gives the return shape. It omits auth/permission requirements and any rate-limit or concurrency notes, keeping it 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?

Four terse, front-loaded sentences with no filler; the side-effect warning leads and the sibling pointer trails. Every clause earns its place.

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

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

For a mutation tool with no annotations and no output schema, the description supplies the safety signal, idempotency, return shape, and the delete alternative. Missing only permission/auth context, which an agent might still need.

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 highlights `active`'s soft-retire behavior, but that meaning is already documented in the schema property, so it adds little beyond the structured field.

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?

Specific verb ('Patch') plus resource ('an existing entity's fields') with the required `id` implied. It explicitly distinguishes itself from the delete sibling, so an agent can route correctly 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?

Names the hard-delete alternative (`calendar_entities_delete`) and states the soft-retire use case via `active`. It stops short of clarifying patch-vs-add boundaries or partial-update expectations, but the main routing decision is covered.

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 load and does so well: it flags the write as side-effectful, warns it is NOT idempotent (duplicate calls create duplicate events), and explains that naive timestamps are rejected and why. It omits permission/auth requirements and whether the target entity must already exist.

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

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

Four tight sentences, each carrying distinct information; the side-effect and non-idempotency warnings are front-loaded before the parameter constraints and the follow-up pointer. 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 5-required-parameter mutation tool with no annotations and no output schema, it covers the critical risks (duplication, timezone format, return field) and names the natural next call. It could still say more about failure modes, entity resolution, or permissions.

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 already 100%, so the baseline is 3, but the description adds real meaning: the timezone requirement is stated as a hard rejection rule with rationale (ambiguity once stored as UTC), and it documents the returns shape. It adds no clarification for entity, type, notes, source, or original_timezone 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 ('Add a one-off time window ... to an entity') and enumerates concrete examples (downtime, maintenance, delivery, shift). An agent can distinguish it from calendar_events_update/delete/list and from calendar_entities_* without opening any schema.

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

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

Explicitly routes the agent to the sibling calendar_events_conflicts for overlap checking, and the 'one-off' qualifier implies when this tool is appropriate. It stops short of stating exclusions, e.g. that recurring schedules should not go through 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, the description carries the full burden and does so well: it discloses the read-only/no-auth/no-rate-limit profile, that results are 'Computed on demand, nothing is persisted', and the buffer default semantics (config setting, 0 = off, per-call override). This is rich behavioral 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?

Front-loads the safety profile, then conflict types, then computation/storage behavior, then the buffer rule, then the return shape and a sibling pointer. Each sentence earns its place and nothing is redundant.

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

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

No output schema exists, but the description supplies the return shape ({conflicts, count, buffer_minutes, events_considered}) and covers storage, defaults, and scoping. 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%, so the baseline is 3, but the description adds meaning beyond the schema by naming the backing setting (calendar.min_buffer_minutes), explaining that the default comes from it and that buffer_minutes overrides per call, and clarifying entity scoping includes linked neighbors.

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 ('Report scheduling conflicts in a window') and enumerates the three conflict categories it detects (overlap, linked_overlap, insufficient_buffer). It also distinguishes itself from the sibling calendar_events_list, so an agent can route without opening schemas.

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

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

Gives clear operating context ('Read-only; no side effects, auth, or rate limits') and points to the alternative ('See also calendar_events_list with include_conflicts'). It stops short of an explicit rule for when to choose this tool over that alternative, so it is clear context without full 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?

With no annotations provided, the description carries the full behavioral burden and does a fair job: it flags DESTRUCTIVE explicitly and explains idempotency ('deleting an already-absent id is a no-op'), which is the kind of trait an agent cannot infer from the schema. It omits auth/permission requirements and any side effects such as attendee notifications or whether recurrence masters are affected.

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 tight sentences, zero filler, and the most consequential fact ('DESTRUCTIVE') is front-loaded. Every clause conveys distinct information: risk, operation, idempotency semantics, return shape.

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 deletion tool with no annotations and no output schema, the description covers the essentials: what it does, that it is irreversible, that repeats are safe, and the return shape `{success, existed}` — which usefully compensates for the absent output schema. Only permission/prerequisite context is missing.

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

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

Schema description coverage is 100% for the single `id` parameter, so the baseline is 3. The description adds only the phrase 'one event by id' — no format, range, or source for the id beyond what the schema already states.

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 with scope: 'Delete one event by id.' An agent can immediately tell this removes a calendar event rather than an entity or a file. It never names or contrasts against the closest siblings (calendar_events_update, calendar_events_list), so it stops short of full sibling differentiation.

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 by 'DESTRUCTIVE' and the single-event scope, which is enough to know this is the removal path. However, there is no explicit when-to-use, no prerequisites, and no guidance on choosing between this and calendar_entities_delete or calendar_events_update for corrections.

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 behavioral burden and does well: it declares read-only, no side effects, no auth, and no rate limits, plus the half-open interval semantics and the return shape. It stops short of disclosing pagination/limit behavior or what a conflict record looks like, keeping it from 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?

Front-loaded with the safety profile, then scope, then optional behavior, then the routing alternative. Four dense clauses that each earn their 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?

No output schema exists, but the description supplies the return shape `{events, count, conflicts?}` and covers the one non-obvious edge case (half-open boundary). Everything an agent needs to call it correctly is 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 baseline is 3, but the description genuinely adds meaning beyond the schema: the half-open window semantics for `from` (an event ending exactly at `from` is excluded) and the coupling of include_conflicts to both from/to. This is real added value over the already-documented 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 (List) and resource (events) with precise scope (overlapping a window). It explicitly distinguishes itself from the sibling calendar_events_conflicts, so an agent can route between them without opening either schema.

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

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

Gives explicit context for optional filtering (entity/type) and a clear alternative: 'For conflicts alone, prefer calendar_events_conflicts.' It also tells the agent when to set include_conflicts. Nothing is left to inference.

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

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

With no annotations, the description carries the full burden and does reasonably well: it flags SIDE-EFFECTFUL, discloses the merge-then-revalidate behavior, and names a concrete failure case (`ends_at` below `starts_at` throws), plus the return shape. It omits permission/auth requirements and reversibility, which are relevant for a mutation.

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 tight sentences, front-loaded with the SIDE-EFFECTFUL warning, then the operation, then the validation/return contract. No filler.

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

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

Given 9 params already fully documented by the schema, no output schema, and no annotations, the description covers the essentials: what it mutates, the validation failure mode, and the return shape. Only auth/permission context is missing, which is minor against otherwise complete coverage.

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, but the description adds meaning beyond the schema by explaining that fields like entity/title can be patched and by describing the interaction constraint between `ends_at` and `starts_at`. It still leaves most parameter syntax (ISO formats, freeform fields) to 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 (patch) and resource (an existing event), and enumerates the kinds of changes allowed (move, retitle, re-home to another entity). The word 'existing' cleanly separates it from calendar_events_add and calendar_events_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?

Usage is implied by 'Patch an existing event', which signals this is for modifying, not creating. However, no explicit when-to-use/when-not guidance or named alternatives (e.g. add/delete) are given, and no prerequisites are stated.

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 well: read-only, no side effects, no auth, no rate limits, UTC times so no VTIMEZONE is needed. It also discloses the return shape (`{ics, event_count}` with a JSON string field), which is essential given there is no output schema.

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

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

Three tight sentences, front-loaded with the safety/behavioral profile before the format and return details. Every clause earns its place; nothing is repeated from structured data.

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 read tool, the description covers safety profile, output format standard, timezone handling, intended consumer, and return shape. An agent has everything needed to call it and interpret the result.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters with types and semantics (ISO 8601 with timezone, entity filter, X-WR-CALNAME default). The description adds only the generic notion of a 'window' and does not extend meaning beyond the schema. Baseline 3 is correct here.

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: export events in a window as an RFC 5545 ICS calendar. The namespaced 'calendar_export_ics' plus the explicit output format makes it instantly distinguishable from calendar_events_list and the entity CRUD 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?

Gives clear context for when this is the right tool: producing an importable ICS file for Outlook/Calendar apps. It stops short of naming the alternative (calendar_events_list) for simply inspecting events, so the routing decision is implied rather than 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 and does so richly — writes to disk AND the SQLite FTS5 index, 'project' is REFUSED, no external auth, no rate limits, auto-creation of missing directories, and per-item failure isolation (errors[] with the rest of the batch still committing). This is exactly the behavioral context an agent needs before calling a write 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?

Front-loads the core action and batching rule, and every sentence is substantive. It is long and info-dense with somewhat sprawling ordering (returns shape and directory auto-creation sit mid-paragraph), so it is not maximally tight, but nothing is padding.

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

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

For a mutation tool with no annotations and no output schema, the description covers creation side effects, destination constraints, format routing, failure semantics, and even the return shape ({created_count, error_count, created, errors}). An agent has everything needed to invoke it correctly across the batch and single-file cases.

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 already 100%, yet the description adds routing semantics beyond it: format='mmd' auto-routes to the mermaid/ bucket (kind ignored), format='html' requires destination='knowledge' and routes to html/ (kind ignored), and format defaults to 'md'. The destination='knowledge' vs 'kontexta' (project_id required) distinction is clarified further than the schema alone.

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 ('Create'), the resource (markdown, mermaid, or HTML files), the container (knowledge base or project), and the batching scope (up to 200 per call). It also names the sibling used for modification ('files_update'), so an agent can distinguish it from other files_* tools without opening a schema.

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

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

Explicitly routes the agent: use 'files_update' to modify existing files, single-element array for the one-file case, and per-destination rules ('kind' strictly required for md to knowledge, project REFUSED). When/when-not conditions are stated rather than implied.

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 and does so: it discloses permanence, the KB-vs-project disk/index asymmetry, non-idempotency with per-item errors on unknown IDs, absence of external auth or rate limits, per-ID failure isolation, and the partial-success norm. This is far beyond what a bare 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?

Content is dense and front-loaded with the DESTRUCTIVE warning and the core action, and nearly every sentence carries operational weight. It is on the long side, but for a destructive batch tool the length is largely earned rather than padding.

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

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

With no annotations and no output schema, the description still supplies safety profile, per-class behavior, failure semantics, and the response shape `{deleted_count, error_count, deleted, errors}`. An agent has everything needed to call it correctly and interpret partial failures.

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 single `ids` parameter is fully documented including minItems/maxItems, so the baseline is 3. The description restates the single-element-array convention and the 500 cap, adding convenience but little new syntax or format 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 with scope: 'Permanently delete one or more files by ID (up to 500 per call).' It also distinguishes the two file classes (KB files vs project reference files) and their differing delete semantics, so it is clearly separable from siblings like files_update or tags_remove.

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 'Use only when the file is truly obsolete' gating, two named alternatives for the deprioritise case (tags_remove, tags_set_favorite), and a preview workflow via files_list with the same filter. When-to-use, when-not, and alternatives are all covered.

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 behavioral burden and does well: it discloses no token cost from the body, local execution, and no auth or rate limits, and enumerates exactly what fields are returned. It does not cover error behavior or edge cases (e.g., missing/invalid IDs), which keeps it from 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?

It is front-loaded with the core benefit and the body-cost rationale before the detail. The field enumeration, behavioral traits, usage rule, and parameter note each contribute, though the field list is dense enough that it could be trimmed slightly.

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?

There is no output schema, so the description must convey the return shape — and it does by listing tags, size, est_tokens, history depth, related ids, backlinks, project, folder, and last edited. Cost, auth, and usage context are also covered, leaving it essentially complete for a single-parameter metadata 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 description coverage is 100%, so the parameter is already documented, and the description mostly restates it ('id' must be a valid integer file ID). The only added nuance is the 'integer' constraint versus the schema's declared type 'number', which is marginal value over the schema.

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

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

The description states a specific verb and resource — 'Return everything ABOUT a file without pulling its content' — with the crucial scope boundary (metadata, not body) front-loaded. It clearly distinguishes itself from files_read and the other chained siblings, so an agent can tell them 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?

It explicitly names when to use it ('when you'd otherwise chain files_read + tags_list + files_get_history + files_find_related') and the decision it supports ('just to decide whether to actually read the file'). The alternative tools and the condition selecting this one are both spelled out.

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: it declares the tool is read-only with no side effects, no auth, and no rate limits, and enumerates all four possible status outcomes plus exactly which fields are returned on divergence.

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 tightly packed sentences, front-loaded with purpose, then return shape, then the read-only caveat, then usage routing. Every sentence earns its place 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?

No output schema exists, and the description compensates by describing the status enum and the divergence payload in detail. Combined with the routing advice to projects_refresh_index, an agent has everything needed to call and act on this 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?

The single parameter file_id has 100% schema coverage, so the schema already documents it. The description adds no syntax, format, or constraint details beyond what the schema provides; baseline 3 applies when the schema does the heavy lifting.

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

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

States a precise verb+resource: "Diagnose drift between one file's disk content and its FTS index." It immediately distinguishes itself from the sibling files_get_diff by explicitly saying it returns diagnostics, not a full diff.

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

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

Explicit when-to-use ("Use when search results look stale"), explicit follow-up action ("if status is diverged or no_index_row, run projects_refresh_index"), and an explicit alternative for the overlapping case (files_get_diff for full diffs). Nothing is left to inference.

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

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

With no annotations provided, the description carries full behavioral burden and does it: read-only, no side effects, no auth, no rate limits, plus the return shape (annotated rows with shared_tag_count and shared_tags) and the default limit. Nothing about operational behavior 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 compact sentences, front-loaded with purpose and ranking, then behavioral facts, then empty-result routing. No sentence is filler; each adds a fact the agent needs.

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 3-param read-only tool with no output schema, the description covers purpose, behavior, return fields, empty-result meaning, and sibling routing. It is self-sufficient 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 all three parameters are documented in the schema itself, and the description largely restates them (kind narrows to one content class, default limit 10). The only marginal addition is the ranking field semantics, so 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?

States a specific verb (find), resource (other files sharing tags), and ranking rule (shared_tag_count descending) tied to a given file. It is immediately distinguishable from content-based 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?

Names explicit alternatives and the condition selecting them: content-based discovery goes to files_search/files_regex_search, and label bootstrapping goes to tags_suggest. It also interprets the empty-result case, which is exactly the decision an agent faces mid-call.

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: read-only, no side effects, auth, or rate limits, plus argument-order semantics ("reversing the args inverts the diff") and an error condition ("Throws if either hash is unknown"). This is exactly the behavioral context an agent needs.

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?

Front-loaded with the return value, then behavior, then ordering, then error, then usage. Every sentence earns its place with no padding.

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

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

No output schema or annotations exist, yet the description fully covers what is returned (unified diff), safety profile, argument ordering, failure mode, and relationship to files_get_history. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% (baseline 3), and the description adds real meaning: commit_a is treated as the earlier side and reversing args inverts the diff. This explains ordering semantics that the schema's field descriptions only partially imply.

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 the unified diff") and resource scope ("of one file between two commit hashes"). It clearly defines the range being diffed. It does not explicitly disambiguate from the sibling files_diff_against_disk, though the commit-hash scope implies the distinction.

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

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

Explicit when-to-use guidance: "Use after `files_get_history` to see WHAT changed, not just THAT it changed," and notes the hashes are typically obtained from that tool. It gives clear context but names no alternatives/exclusions to route away from.

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 behavioral burden and does so: it declares read-only, no side effects, no auth, no rate limits, and clarifies which repository is read (project git repo vs KB backup repo). It also explains the empty-array case, which is a meaningful edge condition.

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?

Front-loads the core behavior and return shape, then adds behavior, then usage routing. Every sentence contributes something (return contract, repo resolution, safety profile, empty-result meaning, sibling routing) 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?

No output schema exists, yet the description supplies the return envelope (`{file_id, path, history}`), the entry shape, and the empty-array semantics. For a single-parameter read tool, nothing an agent needs to call or interpret 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?

Only one parameter, and schema coverage is 100%, so the schema already documents file_id fully. The description adds mild interpretive value by explaining that the owning repo is resolved from the file (project vs KB), but adds no format or constraint details beyond that. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a precise verb+resource ('Return the git commit history for one file'), plus ordering ('newest first') and the per-entry fields (hash, message, date, author). An agent can immediately distinguish this from files_get_diff or files_restore without opening a schema.

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

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

Explicitly names the use case ('understand a file's evolution before editing or restoring') and routes to two named siblings with their conditions: files_get_diff for exact line changes, files_restore to roll back. Both when-to-use and alternatives are covered.

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 declares read-only, no side effects, no auth, no rate limits, and describes the response shape (per-row tags/est_tokens/size_bytes/content_class plus total_est_tokens for budgeting). It stops short of stating pagination defaults or result ordering.

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?

Front-loaded with purpose, then behavior, then parameter nuances, then usage routing — a logical order with no filler. It is dense with semicolon-joined clauses, so slightly more packed than an ideal single-purpose blurb.

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 8-parameter read tool with no output schema, the description covers the returned row fields, the budgeting token total, filter semantics, and alternatives. Minor gaps remain around pagination limits/ordering, but nothing that would cause a wrong call.

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 already 100%, so the baseline is 3, but the description adds real meaning the schema lacks: the distinction between 'project_id: null' (KB-only) and omitting the field (span everything), and that kind narrows to a single content class. It adds cross-parameter semantics rather than restating field docs.

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 file metadata') plus the scope of its optional filters, and explicitly separates itself from files_search and projects_map. An agent can identify the tool's role 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?

Gives explicit routing: 'Use to browse known structure; for keyword/content lookup use files_search; for a denser whole-vault dump use projects_map.' Names both alternatives and the condition that selects each.

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 discloses authentication ('no auth or limits'), the local operation scope, and the path-resolution constraints. It does not state overwrite behavior or what happens to an existing file at the destination, leaving one behavioral gap 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?

Front-loads the core purpose, then layers constraints and the alternative mode in a compact four-sentence block. Dense but every sentence adds actionable information; only the parenthetical examples could be trimmed.

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?

No output schema or annotations exist, and the description covers constraints, both calling modes, and auth/limit behavior sufficiently for correct invocation. Only destination-collision/error semantics are unaddressed.

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

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

Schema description coverage is 100% so baseline is 3, but the description adds meaning beyond the schema by specifying that new_path 'must be absolute and resolve INSIDE the file's owning project or global knowledge directory' and clarifying the kind-mode semantics (subfolder path preserved).

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

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

States a specific verb+resource ('Move/rename a KB file') and immediately scopes it with the constraint that project-repo files are refused. An agent can distinguish this from files_create/files_update/files_delete without opening any 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?

Gives explicit when-not conditions (project-repo files refused, cross-project moves rejected) and an explicit alternative calling mode (pass kind='dictionary'|'note' with no new_path to move into the mirrored class tree). The when-to-use and when-not are both spelled out.

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 supplied, so the description carries the full disclosure burden and does so: 'Read-only; no side effects, auth, or rate limits.' It also documents batch failure semantics ('per-ID failures isolated, batch never partial-throws'), which is non-obvious behavior an agent needs before choosing a mode.

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?

Front-loads the core action, then packs modes, constraints, behavioral guarantees, and response shape into dense, well-ordered sentences with no filler. It is long but nearly every clause carries an operational constraint, so little could be cut without losing routing 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?

With no output schema provided, the description compensates by describing all three response shapes (single file object, partial-content object, and the {files, total_est_tokens, error_count, errors} batch envelope). For a 5-param, nested-object tool with no annotations, nothing needed to call it correctly appears to be 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 constraints the JSON schema cannot express: exactly one of id/path/ids is required, section/lines are mutually exclusive, and both are valid only with id (not ids or path). It also clarifies the path must be the exact indexed absolute path, which sharpens a fuzzy parameter.

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

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

States a specific verb+resource ('Read one or more files, in full or in part') and enumerates every mode with the exact parameter combination that triggers it. It also distinguishes itself from a sibling by naming files_describe as the inspect-without-cost alternative, so an agent can route correctly without opening another 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?

Each mode is tied to a concrete condition (single-by-id, single-by-path, batch up to 200, partial-by-heading, partial-by-line-range), and it explicitly routes inspection-only work to files_describe. It stops short of addressing other close siblings like files_read_outline or files_regex_search, so the guidance is clear but not fully exhaustive.

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: it declares read-only behavior, no side effects, no auth requirement, and no rate limits — exactly the behavioral context an agent needs. It also discloses the empty-result edge case and its different meaning (no headings versus no content).

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

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

Three sentences, each earning its place: purpose, safety profile, then the decision guidance and fallback. The core capability and return shape are front-loaded before the routing advice.

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?

No output schema exists, but the description compensates by naming the returned fields and explaining the empty-outline case. For a simple single-parameter read tool with a fully covered schema, nothing an agent needs in order to 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 description coverage is 100%, so the single file_id parameter is already documented (albeit thinly as 'File ID'), which sets the baseline at 3. The description adds marginal value by using the parameter in example calls, implicitly flagging that this tool uses file_id while files_read uses id, but it doesn't explain what a file ID is or how to obtain one.

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 a flat list of markdown headings for one file') and enumerates the exact return fields (level, text, line, byteStart, byteEnd). This clearly distinguishes it from siblings like files_read (full body) and files_regex_search without needing 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?

Explicitly positions the tool as a 'cheap probe before files_read({ id, section }) or files_update({ file_id, section, content })', naming the alternatives and the condition (avoid spending tokens on the full body). It also covers the exclusion case: an empty outline means no headings, so fall back to files_read or files_read({ id, lines }).

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: read-only with 'no side effects, auth, or rate limits,' disclosed caps (500 files / 10 hits per file, 100/500 in single-file mode), the `files_truncated` cap signal, response-shape change in single-file mode, and failure mode ('Invalid regex throws'). This is unusually complete for an unannotated tool.

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

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

Front-loads purpose and the routing rule, then packs caps and mode details; every sentence carries information. It is somewhat dense with parentheticals, which slightly costs readability, but nothing is wasted.

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

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

Despite having no output schema, the description explains the return shape for both modes, cap behavior, and error behavior. Combined with the 100%-covered schema, 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%, so the schema already documents parameters, and the baseline would be 3. The description goes beyond by consolidating which parameters matter per mode (e.g., `project_id`/`kind` ignored when `file_id` is set) and stating the mode-dependent response shape, adding mode-selection meaning over the field-level docs.

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

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

Opens with a specific verb+resource ('Match a JS regex against file bodies') and immediately distinguishes itself from the sibling FTS tool by name (`files_search`) and by why it is slower ('reads each file's content'). An agent can tell it apart from `files_search` without opening either schema.

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

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

Explicit when-to-use: 'use only when FTS misses substrings, URLs, or code identifiers,' naming the alternative (`files_search`). It also gives the distinct trigger for the second mode ('Pass `file_id` to instead scan just that one file') so the agent knows which mode to pick and when.

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

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

With no annotations, the description carries the full burden and delivers: DESTRUCTIVE, uncommitted content is lost, a file-watcher race condition may apply, no external auth or rate limits, and the exact return shape. This is unusually complete behavioral disclosure 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?

Dense but front-loaded with the DESTRUCTIVE warning, and every sentence carries distinct information (precondition, data-loss, race, auth, return shape, scope). It reads as a compact block rather than flowing prose, but no sentence is 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?

No output schema and no annotations exist, yet the description supplies the return shape, the safety profile, the prerequisite, and the destructive consequences. An agent has everything needed to invoke it correctly without guessing.

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 real semantic constraints beyond the schema: hash must originate from files_get_history for this specific file, and foreign hashes throw. That constraint meaningfully changes how the agent sources the parameter.

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

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

States a specific verb and resource (overwrite on-disk content with a git-commit version), names the follow-on effect (re-index FTS), and distinguishes itself from siblings like files_update, files_delete, and files_get_history. An agent can tell exactly what this does 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?

Explicitly scopes the use case ('Use only to undo accidental edits or recover a known-good version') and states a hard prerequisite: the hash MUST come from files_get_history for THIS file, with foreign hashes throwing. It routes the agent to the correct sibling for obtaining the input.

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 behavioral burden — and it does disclose ordering semantics (dictionary-wins on conflict, then BM25), truncation behavior (rank-order fill until budget, overflow to meta.skipped[]), and that FTS tokenisation will miss URLs and substrings. It also asserts 'read-only; no side effects, auth, or rate limits'. This exceeds the annotations bar but leaves the actual return field set and sufficiency-check behavior of check_sufficiency only lightly characterized.

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?

Purpose and default behavior are front-loaded in the first sentence, and every clause carries real information (mode switch, ordering, tokenisation caveat, filter semantics). It is however one dense wall of prose with no separation between the default-mode story, the bundle-mode story, and the filter notes, which makes it heavier to parse than it needs to be.

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 10-parameter tool with no output schema, the description supplies the missing contract: the default response shape (match_excerpt, title_highlight, total_est_tokens), the alternate shape ({bundle, meta:{included, skipped}}), defaults, and filtering semantics. An agent has enough to call it correctly and to choose between modes.

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; most description detail (tags all-match, max_tokens default 12000, format semantics) merely restates the schema. The one genuinely additive nuance is the project_id distinction — 'null searches only the KB; omit the field to span everything' — which the schema does not spell out. Marginal net gain.

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

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

States a specific verb+resource+mechanism ('Full-text (SQLite FTS5) keyword search across files') and immediately distinguishes the default mode from the include_bodies mode. It also names the sibling to fall back to (files_regex_search), so an agent can differentiate without opening any 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?

Explicit routing: use default mode for ranked snippets, use include_bodies 'instead of files_search + N×files_read when you need several related files as one context blob', and fall back to files_regex_search for URLs/hyphenated/partial substrings. Both the when and the alternatives are stated.

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 the repo-refusal constraint, the disk write + FTS5 re-index side effect, the throw-on-missing-heading behavior, that section mode will NOT create a new section, and the absence of external auth/rate limits. It even describes the return payload.

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

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

Dense but front-loaded: the operation and default behavior lead, followed by the section mode, then edge cases and environment notes. Every sentence earns its place, though the single-block paragraph is heavy and could be broken up for scanability.

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 3-param mutation tool with no annotations and no output schema, the description covers side effects, failure modes, environment constraints, and even the return shape (updated metadata with token counts). Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: `content` semantics depend on whether `section` is set, `section` matching is case-insensitive exact-string after trim, and the heading line/siblings are preserved. The throw condition further informs `section` usage.

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

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

States a specific verb+resource ('Rewrite a KB file') and immediately distinguishes the two operating modes (full-body default vs section-scoped rewrite). It also differentiates from files_create by framing it as a rewrite and by the repo-refusal rule.

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

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

Gives clear when-to-use guidance for the two modes, including the motivating benefit of `section` (saves context budget) and the failure condition. It stops short of naming a sibling alternative or a general 'when not to use update vs create' rule, which keeps it below a 5.

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

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

With no annotations, the description carries the full burden and does so thoroughly: idempotency, the exact rejection set (empty names, null bytes, leading separators, `..` segments) with the isError outcome, the disk mkdir side effect with the note that no DB rows are written until a file lands inside, and the absence of auth or rate limits.

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

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

Dense but tightly front-loaded: purpose first, then idempotency, then rejections, then side effects, then return shape. Every clause carries distinct operational information and none is 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?

Despite having no output schema and no annotations, the description covers purpose, validation failures, side effects, and the return shape `{path, base_path}`, which is exactly what an agent needs to call this correctly. Nothing material is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description earns above baseline by adding semantics the schema lacks: that passing a `project_id` is actively refused (not merely ignored) and that nested-path segments are validated against `..` traversal.

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

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

States a specific verb+resource (create a folder in the KB) and immediately scopes it by declaring that a `project_id` is refused because kxta never writes into a project repo. This distinguishes it from siblings like folders_list, folders_delete, and files_create without requiring schema inspection.

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

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

Gives clear conditions: nested paths like `notes/inbox` are supported and create intermediates, and project_id is refused. It does not explicitly name an alternative sibling (e.g., where to put files once the folder exists), so it stops short of full when-to-use/when-not routing.

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

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

With no annotations, the description carries the full burden and does so richly: destructive/recoverable semantics, the project_id refusal returning isError with the race-condition rationale, git-backup caveat, and no auth/rate limits.

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

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

Front-loads 'DESTRUCTIVE' and packs the recursion, refusal, recovery, and return-value facts into a tight paragraph with no filler sentences.

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-param destructive tool with no annotations and no output schema, the description supplies every needed fact: scope, refusal condition, irreversibility, backup caveat, and the return shape.

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 value by explaining WHY project_id is rejected (file-watcher race) and cross-references the name validation rule from folders_create, exceeding what the schema states.

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 ('recursively delete a folder under the KB AND every file inside it') with explicit scope (disk + FTS rows), which clearly separates it from folders_list, folders_create, and single-file 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?

Provides an explicit exclusion (refuses when project_id is supplied) plus the alternative path ('remove project content via your editor instead'), and notes the recursive scope that selects this over single-file deletion.

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: it declares read-only status, absence of side effects, no auth requirement, no rate limits, and the specific failure mode ('Throws if project_id references an unknown project'). It also describes the return payload shape and the relative-vs-base_path semantics, which is behavior an agent needs before chaining into files_create.

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

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

Three dense sentences, front-loaded with the core operation, then return contract, then usage routing. No filler, and each clause carries information the agent can 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?

No output schema exists, yet the description supplies the return shape ({folders, base_path}) and the crucial relative-path caveat, plus error behavior and usage routing. Nothing needed to call this 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 schema already documents that null/omitted project_id lists KB folders, so the description largely restates it. It adds only the error condition for an unknown project id, which is more behavioral than parametric. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb ('List') and resource ('folder paths') with explicit scope ('under a project root or the Knowledge Base when project_id is null/omitted'). It is immediately distinguishable from siblings like folders_create, folders_delete, and files_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?

Explicitly names two use cases ('discover where to drop a new file via files_create's folder argument' and 'navigate vault structure') and routes creation to the alternative tool: 'to actually create one use folders_create.' This is a textbook when-to-use plus alternative pointer.

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

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

With no annotations, the description carries the full burden and delivers: token is single-use, tokens expire after 60 seconds, side effects mirror the underlying Hand and can be highly destructive, the token itself is the auth (no external auth, no rate limits), and invalid/expired/consumed tokens yield an inert text response rather than an error. This is unusually rich 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?

Front-loads the purpose, then layers prerequisites, risk, and failure semantics in four tight sentences. No filler; every clause adds decision-relevant 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 one-parameter, no-output-schema tool this covers what an agent needs: prerequisite (a pending approval token), timing (60s expiry), risk profile (destructive potential), auth model (token is auth), and failure behavior (inert text, not error). Nothing material 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% for the single token parameter, so baseline is 3. The description goes beyond the schema by explaining the token's origin (returned by confirm-required tools), its lifetime (60s), and its single-use nature, all of which affect how and when the parameter is passed.

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 pair (approve and EXECUTE) plus the exact resource (a previously-issued Hands invocation) and the mechanism (single-use approval token). This clearly separates it from siblings like hands_list and hands_reload, which do not execute anything.

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 the source of the token (any confirm-required Hands tool) and the condition for calling: 'only call when the user has authorised the pending action.' The when-not case is implied by that constraint. It doesn't name an alternative tool, but none exists for this execution step, so the guidance is effectively complete.

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: it declares read-only, no side effects, no auth, no rate limits, and explains data provenance (per-project kontexta.json loaded at register time). It also discloses that schema mode returns a static document unrelated to any registered hand, a non-obvious behavioral 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?

Front-loads what the default mode returns, then the schema-mode override, then safety notes and routing. Dense and mostly waste-free, though the parenthetical enumeration of schema contents is long and could be trimmed.

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?

No output schema and no annotations, yet the description enumerates the returned fields for list mode and characterizes the schema-mode payload, so an agent knows what it will receive. Safety, provenance, and routing are all covered.

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 meaning beyond the schema: that the schema output is a static authoring reference (JSON schema, validation rules, security guarantees, limitations, example) and is unrelated to any specific registered hand, plus motivation for when to set it true.

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 precise verb and resource ('List every Hands command tool currently registered') and enumerates the projected fields (project scope, tool name, danger level, confirmation flag, description). It also distinguishes the dual mode from siblings like hands_reload and hands_confirm by naming them.

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

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

Explicitly routes usage: default mode to discover side-effectful project commands, `schema: true` when helping a user author or fix a kontexta.json, and `hands_reload` after editing one. Covers when-to-use for both modes and names the follow-up 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, the description carries the full burden and does so well: it discloses the side effect scope (running session's tool inventory only, no disk writes), idempotency, absence of external auth/rate limits, and the shape of per-project load results including validation 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?

Dense but front-loaded: the action and its effect come first, then side-effect/auth caveats, then invocation guidance. Every sentence adds distinct information 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?

Despite no output schema, the description explains what is returned (per-project registered/disabled counts and validation warnings), and covers side effects, idempotency, and auth, leaving nothing an agent needs 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?

Zero parameters, so the schema-based baseline is 4; the description confirms 'Takes no parameters', leaving no ambiguity for the agent about arguments.

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?

Specific verb ('Re-scan', 'rebuild') plus resource ('registered project's kontexta.json', 'live Hands tool registry'), with the concrete consequence that newly-declared tools become callable and removed ones disappear from tools/list. It also differentiates itself from sibling hands_list by pointing to it for 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?

Explicitly states when to invoke: 'Use after editing a kontexta.json mid-session', and routes schema queries to hands_list({ schema: true }). It gives clear context but no explicit when-not-to-use or contrast against siblings like admin_refresh_session_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, the description carries the full behavioral burden. It helpfully discloses the mutation target (journal_meta.status_latest) and the intent (mark entries as upgraded), but says nothing about idempotency, error handling for unknown slugs, or required permissions.

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: the first front-loads the trigger condition, the second states the effect. Every phrase 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?

For a one-parameter mutation tool with no output schema and no annotations, the description covers purpose, trigger, and effect adequately. Minor gaps around idempotency/permission behavior keep it from being fully complete.

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

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

Schema description coverage is 100% and the single task_slugs parameter is already documented in the schema. The description adds only framing ('affected task slugs'), 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 names a specific verb-plus-resource ('commit upgrades' for journal entries) and states the resulting effect on journal_meta.status_latest. An agent immediately understands the operation. It does not, however, distinguish itself from siblings like journal_write, journal_status, or journal_distill.

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

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

It gives a clear triggering condition: call this 'after dispatching subagents to upgrade mechanical journal entries to LLM-narrative.' That is a genuine when-to-use instruction. It stops short of naming alternatives or exclusions (e.g., what to do if no subagents ran).

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 behavioral burden and does well: it discloses the high-water read, topic grouping, mechanical markdown writes, high-water advancement, idempotency, and auto-provisioning of project rows for orphan slugs. It still omits permissions, partial-failure behavior, and whether raw events are retained or deleted.

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 front-loaded sentences with no filler: purpose first, then the key idempotency trait, then the auto-provisioning side effect. Every sentence adds actionable information for selecting and calling the 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 two-parameter, no-annotation pipeline tool, the description is nearly complete: it explains the pipeline steps, idempotency, and project-row provisioning. It lacks return-value expectations and failure-mode details, which is a gap given there is no output schema, but the core invocation context is well covered.

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 max_events and project_slug are already documented. The description adds only behavioral context around orphan slugs (e.g. 'default') rather than new parameter-level meaning, matching the baseline of 3 when schema does the heavy lifting.

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

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

States a specific verb and resource — running the distillation pipeline — and details the internal sequence: read events since high-water, group by topic, write entries, advance high-water. This operationally distinguishes it from sibling journal tools like journal_write (manual entry) and journal_housekeep (cleanup), so an agent can identify its role.

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 by explaining the pipeline's function, so an agent can infer it is for distilling journal events. However, it never states when to choose this over alternatives such as journal_write or journal_housekeep, nor does it give prerequisites or 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, the description carries the full burden, and it does disclose two meaningful traits: idempotency (safe to re-run) and destructiveness ('prunes old raw .jsonl files'). However, it omits whether pruning is reversible, what 'the configured retention policy' is or how it is set, and any permission requirements for a destructive maintenance 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?

Three short sentences with zero filler. The operation is front-loaded, and the destructive scope is stated immediately after rather than buried.

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, no-output-schema tool with full schema coverage, the definition covers the essentials, including the two most important behavioral facts (idempotent, prunes files). The remaining gap is the retention-policy configuration and irreversibility details, which are minor given the tool's simplicity.

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 already documents itself, including the default to the current active project. The description only gestures at project scope ('for a project') without adding format or behavioral detail beyond the schema, 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 gives a specific verb+resource ('Run journal retention/archival for a project') and then concretizes it with the actual effects: pruning old raw .jsonl files and archiving cold tasks. That is far more informative than a tautology, but it never names or contrasts the adjacent journal tools (journal_distill, journal_status, journal_commit_upgrades), so an agent must infer the boundary itself.

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

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

There is no when-to-use guidance: nothing says whether this should run on a schedule, after commits, or only when storage pressure exists, and no conditions or exclusions are stated. 'Retention/archival' implies a maintenance context, but that is inference rather than explicit instruction.

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. 'Report' implies a read-only operation, but the description says nothing about permissions, side effects, cost, or whether the call touches or mutates the journal. For a tool with zero annotation coverage, this leaves the agent guessing.

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 single front-loaded sentence with no filler, and the resource is named before the qualifying scope. It is efficient, though borderline under-specified rather than genuinely 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?

There is no output schema, so the description is responsible for telling the agent what comes back, and it does not explain what a 'backlog' figure or 'high-water mark' actually represents or how it is formatted. Combined with the absence of annotations, the definition is too thin to let an agent interpret or act on the result.

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

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

Schema description coverage is 100% and there is only one optional parameter (project_slug, documented as defaulting to the current active project), so the schema already does the heavy lifting. The description adds no meaning beyond it, which is the baseline 3 case for a fully documented single parameter.

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

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

States a specific verb ('Report') and a resource pair ('journal backlog and high-water mark for a project'), so the agent knows this is a read/diagnostic operation rather than a write. It does not, however, differentiate itself from the other journal_* siblings (journal_write, journal_housekeep, journal_distill, journal_commit_upgrades), and 'high-water mark' and 'backlog' are domain jargon left undefined.

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

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

No guidance on when to call this versus journal_write, journal_housekeep, or journal_distill, and no prerequisites or conditions are stated. The agent must infer usage purely from the name and the one-word verb.

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 discloses file auto-creation, that same-day appends return the same file_id, the storage layer for notes (Layer 1 agent_note events), and the return shapes for each mode. It omits auth/permission requirements and error behavior.

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

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

Front-loaded purpose followed by kind-by-kind breakdown, with return values parenthesized inline so the agent can scan quickly. It is dense and fairly long, but nearly every clause carries useful information rather than 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?

There is no output schema, so the description correctly supplies return shapes per mode, and with no annotations it also covers storage semantics and file behavior. This 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 description coverage is 100%, so the baseline is 3; the schema already documents each field's per-kind requirement. The description restates the kind-to-required-field map and adds what each kind semantically means, but adds little about parameter syntax or formats 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 concrete verb and resource ('Write one event to the current project's journal') and then enumerates the three distinct modes with what each one does and stores. This clearly separates it from sibling journal tools like journal_distill, journal_status, and journal_housekeep.

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 mode-specific selection guidance, notably the explicit 'use when the user redirects what you're working on' condition for kind='intent'. It does not, however, state when not to use this tool or name alternative siblings for capturing information.

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

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

With no annotations, the description carries the burden and does so well: it declares read-only, no side effects, no auth, no rate limits. It also discloses the derivation logic behind `has_hands`. It stops short of describing ordering/pagination or volume, so not a full 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?

Front-loaded with what it lists and its key output field, followed by behavior, then routing guidance. Three tight sentences, each earning its place 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?

With no output schema and no parameters, the description compensates by enumerating the returned fields and the derivation rule for the derived flag, and it covers the safety profile. An agent has everything needed to call and interpret 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?

Zero input parameters, so the baseline is 4. The description adds value by explaining the meaning of the derived `has_hands` output flag rather than leaving it opaque, though it does not discuss any return-shape nuances beyond field names.

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 (List) and resource (every registered project) and enumerates the exact fields returned, including the derived `has_hands` flag with its derivation rule. It explicitly distinguishes itself from `projects_register` and `hands_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?

Gives the primary use case explicitly ('to find the project_id to pass to scoped tools') and names concrete downstream tools, then states when to use alternatives (register with `projects_register`, inspect Hands tools with `hands_list`). Nothing is left to inference.

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

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

With no annotations provided, the description carries the full burden and does so: it declares read-only, no side effects/auth/rate limits, discloses the max_lines cap, and reveals that the response includes est_tokens and may emit a warning field past KONTEXTA_PROJECT_TOKEN_WARN. This is unusually rich disclosure for a read tool and covers cost/truncation behavior an agent needs.

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

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

Dense but front-loaded: purpose first, then behavior, then defaults, then the routing hint. Nearly every clause earns its place, though the sentence is packed enough that a reader must parse multiple clauses before reaching the 'use this when' guidance at the end.

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?

No output schema exists, yet the description discloses the return shape (indented outline, est_tokens, warning field) and the truncation cap, plus scope and default behavior. For a 4-parameter, fully-defaulted read tool, nothing an agent needs to 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 description coverage is 100%, so baseline is 3; the description adds value by restating defaults (include_tags=true, show_titles=true, max_lines=5000) and clarifying that project_id null means KB-only while omission means everything — a subtle distinction an agent could easily get wrong from the schema alone.

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 a compact indented outline of folders, file titles, tags, and IDs.' It also names the sibling it contrasts with (files_list's JSON) and explicitly distinguishes its output format from that alternative, so an agent can differentiate it 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?

Provides explicit when-to-use ('to orient yourself in an unfamiliar vault or project') and an explicit alternative with its selecting condition ('for keyword lookup use files_search'). It further clarifies scope selection via project_id null vs omitted semantics.

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 flags SIDE-EFFECTFUL writes/updates/deletes, clarifies the prune is destructive on index rows but never removes files from disk, notes idempotence ('running twice is a near no-op'), documents skip rules (>5MB, `node_modules`, `.git`, `dist`, `build`), and states there is no external auth or rate limiting.

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?

Front-loaded with purpose, then scope branches, then the destructive warning in caps for scannability, then constraints and return shape. Every sentence adds an operational fact; none is filler, despite the length being justified by a no-annotation, 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?

Even without an output schema, the description supplies the return shape `{scope, newly_indexed, refreshed, pruned}`, covers both scope modes, states side effects and idempotence, and gives a usage trigger. Nothing an agent needs to invoke it safely and correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema by explaining what each branch of `project_id` does (project re-runs `discoverFiles`; KB walks `knowledge/`, ingests new .md, reindexes drifted hashes, prunes missing files). This is semantic value the schema's one-line description does not supply.

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

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

Opens with a specific verb+resource ('Reconcile the FTS index against disk') and immediately splits behavior into two precise scopes: project (`project_id` set → `discoverFiles`) and KB (`project_id` null → walks `knowledge/`). An agent can tell exactly what this does without opening the schema, and it is clearly distinguishable from index-adjacent siblings like `files_diff_against_disk`.

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 an explicit trigger: 'Use after editing files outside Kontexta, or when `files_diff_against_disk` reports drift.' It names the sibling tool that signals when this one is needed, and the branch semantics tell the agent which mode to select via `project_id`.

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 disk writes, recursive scanning/indexing, Hands tool registration, idempotency ('updates its metadata without data loss'), and the absence of auth/rate limits. It also distinguishes fatal errors (missing path) from non-fatal scan warnings, which is exactly the behavioral detail an agent needs.

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?

Labeled sections (SIDE EFFECTS, AUTH/RATE LIMITS, PARAMETERS, RETURNS, ERROR CONDITIONS) front-load the core action and make the long content scannable. Every section conveys distinct information 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?

No annotations and no output schema exist, so the description must cover both behavior and returns — and it does, enumerating the return object fields and the error/warning split. For a 3-param mutation tool, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully enriches the parameters: it specifies that path must be absolute, forbids guessing from the workspace, instructs the agent to prompt the user, and describes the failure mode. It adds real semantic value beyond the schema strings.

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 ('Register a new project and link it to the Kontexta knowledge system') and the side-effects section clarifies the scope (indexing markdown, registering Hands tools), which implicitly separates it from read-only siblings like projects_list. It never explicitly names a sibling (e.g. projects_refresh_index or projects_map), so it stops short of full differentiation.

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

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

Gives clear operational context: it tells the agent not to guess the path from the active workspace and to ask the user when only a name is given, and notes it fails on a nonexistent path. There is no explicit when-to-use-vs-alternatives routing against projects_refresh_index or projects_map, but the guidance it does provide is 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?

No annotations are provided, so the description carries the full burden, and it delivers the key behavioral gotcha: src resolves in both dashboard viewer and PDF/PNG export whereas url works only in the dashboard. It also discloses the exact return shape and that bytes are base64-encoded. It omits overwrite behavior, size limits, and permission requirements for a write tool, keeping it from 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?

Front-loads the action and destination, then the return contract, then the embed guidance, each in one tight sentence. No filler; every clause conveys a distinct, useful fact.

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

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

No output schema exists, but the description enumerates the returned fields (filename, size, src, url) and explains how to consume them, which covers the return contract. For a two-required-param write tool it only leaves mutation edge cases (overwrite, limits) unstated.

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%, with both params (filename, bytes_base64) already documented, so the schema does the heavy lifting. The description only reinforces that bytes are base64-encoded and implies filename maps to the stored resource name, adding no format or constraint detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (Write), resource type (image or other binary resource), and exact destination (shared reports/resources/ folder). An agent can distinguish it from sibling write tools like files_create and resources_clip_url without opening any 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?

Gives explicit, actionable guidance on the returned fields: embed `src` in report HTML and never use `url` because url only resolves in the dashboard. This is clear in-tool usage direction, but it never states when to choose this tool over sibling alternatives (files_create, resources_clip_url), so it stops short of full alternative routing.

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

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

With no annotations, the description carries the full burden and does so thoroughly: SIDE-EFFECTFUL, non-idempotent with no de-dup, auto-classification as content_class='dictionary', anonymous-by-default auth, upstream throttling caveat, and the AUTH_REQUIRED error contract with login_url and retry hint. This is exactly the behavioral disclosure a mutation tool needs.

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

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

Dense but front-loaded: the SIDE-EFFECTFUL warning and non-idempotency come first, then AUTH, then error/return shape. Every sentence conveys actionable facts, though the single-block density is slightly heavy.

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

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

Despite no annotations and no output schema, the description supplies the return shape ({file_id, path, title, source}), the error contract, auth behavior, and side-effect profile. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100% and the schema already documents url, title, and headers (including the AUTH_REQUIRED/retry-with-headers workflow). The description largely restates this, adding only the concrete header examples, 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 names a specific verb+resource with full mechanism: 'fetches an EXTERNAL URL and writes a NEW KB file', then enumerates the pipeline (download, Readability extract, markdown convert, save under knowledge/urlclips/). This is clearly distinguishable from siblings like 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?

'Use to ingest external docs into the KB' gives clear context, and the AUTH section explains when to pass headers (pages behind logins) after an AUTH_REQUIRED error. It lacks an explicit contrast against sibling alternatives (e.g. when to use files_create instead), so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses idempotent behavior ('No-op if it doesn't exist'), which is real value, but stays silent on whether the delete is permanent or recoverable and on any permission requirements 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?

Two short sentences, zero waste, with the action and its scope front-loaded and the idempotency caveat immediately after. Nothing is padded or restated from the 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?

For a single-parameter, no-output-schema tool, the description covers purpose, scope, and the notable no-op behavior. It falls short only on the destructive-operation details (permanence, permissions) and on disambiguating itself from files_delete.

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

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

There is exactly one parameter and schema description coverage is 100%, so the schema already defines filename as a relative path within reports/resources/. Baseline 3 applies; the description adds no path syntax or format detail beyond the schema.

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

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

States a specific verb (delete) and a precisely scoped resource (a file under reports/resources/), which separates it from the sibling resources_add_report. It is less clearly differentiated from files_delete, since neither the name nor the description explains when the reports-scoped variant should be preferred.

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?

There is no explicit when-to-use or when-not-to-use guidance, and the near-twin sibling files_delete is never mentioned. The 'No-op if it doesn't exist' clause implicitly signals safe repeated invocation, but the agent must infer selection between the two delete tools.

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

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

With no annotations, the description carries the full burden and does meaningful work: it discloses the auth requirement for the URL path, the CLI-vs-standalone availability constraint on inline_bytes, and the graceful fallback with a note. It omits any mention of rate limits or permissions beyond 'authenticated dashboard request', so it is strong but not exhaustive.

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?

Front-loaded with the action and output formats, then the default return, then the opt-in variant. Three dense sentences with little waste, though the nested clauses about CLI availability make it slightly heavier than necessary.

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?

No output schema exists, so the description properly names both return shapes ({ url } and { bytes_base64 }) and their conditions. Auth, availability, and fallback behavior are all covered; only granular operational details (limits, error modes) are absent.

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

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

Schema description coverage is 100% and the schema already documents all three parameters, including the inline_bytes CLI caveat and the pdf/png enum. The description largely restates this, adding only the auth context for the URL return, 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?

States a specific verb and resource ('Export an existing HTML report as PDF or PNG') and is immediately distinguishable from siblings like resources_add_report, resources_list_reports, and resources_delete_report. No ambiguity about what the 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?

Explains the default path (web-served { url }) and the condition that selects the alternative (set inline_bytes=true), including when that alternative is unavailable and what happens instead. It does not explicitly compare to sibling report tools, but the default-vs-opt-in routing 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?

No annotations are provided, so the description must carry the full burden. It discloses return values (filename, size, served URL), which is helpful, but does not state whether the operation is read-only (implied by 'List'), auth requirements, pagination, or whether it recurses into subdirectories.

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 concise sentences with zero filler; the purpose is front-loaded and the return information follows immediately. 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 zero-parameter list tool with no output schema, the description provides all essential information: what is listed, where, and what is returned. It is complete enough for an agent to invoke correctly, though minor ambiguities about recursion remain.

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

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

There are no parameters (0 params), and the schema is empty. Per the rubric, 0 params yields a baseline of 4, as the description cannot add parameter meaning beyond an empty schema.

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

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

The description states a specific verb ('List') and resource ('files under reports/resources/'), and specifies the return fields. It clearly scopes to a subdirectory, distinguishing it from broader file-listing siblings like files_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?

No explicit guidance on when to use this tool versus alternatives (e.g., resources_add_report, files_list). The scope implies its purpose, but there are no when/when-not statements or named 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 exist, so the description carries the full burden and does so thoroughly: additive semantics, per-tag idempotency, auto-creation of tag rows, local SQLite persistence, no auth or rate limits, success return shape, and the throw condition on unknown file_id. This is unusually complete 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?

Front-loaded with the core action, then behavior, then return values, then sibling routing. Dense but every sentence carries distinct information; 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?

Covers the write semantics, idempotency, persistence, failure mode, and return shape despite no output schema, and routes to the two relevant siblings. Nothing an agent needs to call this 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 description coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining what the tags parameter does semantically — additive append, idempotency, and auto-creation of unknown tag names — which the schema does not state.

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

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

Opens with a specific verb+resource+scope: 'Append tags to ONE file' — the 'ONE' immediately signals this is single-file, distinguishing it from bulk tagging. Sibling tools tags_search and tags_remove are named, so an agent can route without opening any 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?

Explicit when-to-use ('Use to label a single file') plus explicit alternatives with their selecting conditions: bulk tagging via tags_search, removal via tags_remove. No inference required.

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: it declares read-only behavior, no side effects, no auth or rate-limit requirements, and discloses that the full taxonomy is returned unpaginated. These are exactly the behavioral facts an agent needs that the empty schema cannot supply.

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 sentences, front-loaded with what it does, then usage, then the alternative. Every sentence carries distinct information with no repetition of the name or schema.

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

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

There is no output schema, but the description compensates by naming the returned fields and noting the result is the complete unpaginated taxonomy. Nothing an agent needs to invoke or interpret this call 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 takes zero parameters, so the baseline is 4; there is nothing to disambiguate. The description spends its words on return fields instead, which is appropriate for a no-argument listing tool.

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

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

The description gives a specific verb (list), resource (tags in the global SQLite database), and the exact return fields (id, name, applied count). It explicitly distinguishes itself from siblings like tags_search, tags_suggest, and files_describe, so an agent can pick the right tool without opening schemas.

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