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

With no annotations, the description carries the full burden and does add one important behavior: the call 'Returns immediately' while the daemon removes chunks in the background. However, it does not disclose the destructive/permanent nature of deletion or possible failure/error behavior, which is significant for a delete tool.

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

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

The description is short, front-loaded with purpose, and then gives the async behavior before a scannable Args list. Every sentence adds information and there is no filler.

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

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

Given an output schema and a relatively simple three-parameter tool, the description covers the core purpose, async timing, and all argument semantics. It leaves out irreversibility and error-handling details, but these are not essential for a basic delete invocation.

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

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

Schema description coverage is 0%, and the description compensates fully by explaining all three parameters: name, kind with its allowed values, and collection with its conditional scope. It adds the relationship that collection only applies to kind='document', which the schema does not express.

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

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

The description opens with a clear use-case: remove stale or wrong content before re-ingesting it. The Args section identifies the target resources as documents or collections, making the operation unambiguous. It does not explicitly contrast with sibling tools, but no sibling duplicates this delete operation.

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

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

It gives an explicit trigger ('stale or wrong content before re-ingesting it') and explains why deletion is needed prior to re-ingestion. It does not list when-not-to-use or alternative tools, but the context is sufficient for the provided sibling set.

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 disclosure burden. It explains the synchronous removed-file count return, the background chunk purge, the effect of keep_data, and the error behavior for unknown collections. This is substantive, non-obvious information beyond a simple 'deregisters' statement.

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

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

The description is compact and front-loaded: objective first, then returns/behavior, then error semantics, then parameter definitions. Every sentence provides necessary operational detail with no filler or redundancy.

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

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

The tool has moderate complexity—a mutation with asynchronous behavior, a conditional data-preservation flag, and a specific error mode. The description covers the main action, both parameters, return value, background processing, and error semantics. With an output schema present, no return-structure detail 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 0%, so the description fully compensates by defining each parameter: 'collection' as the collection to deregister, and 'keep_data' with its effect on LanceDB indexed data. Both parameters receive meaningful semantic context beyond their raw schema types.

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

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

The description clearly states the tool's action: 'stop tracking a directory', which is a specific verb and resource. It distinguishes itself from register_directory by its opposite meaning, and from delete by the keep_data vs purge distinction, though it does not explicitly name sibling alternatives.

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 opening 'Use to stop tracking a directory' provides clear usage context, and the keep_data=True vs purge option explains the decision branch. However, it does not explicitly state when not to use it or direct users to alternative tools like delete.

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

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

No annotations are present, so the description carries the disclosure burden. It adds substantive behavioral context by explaining the hybrid vector similarity + BM25 search with Reciprocal Rank Fusion and its recall benefit. It does not explicitly describe data scope or side effects, but as a search tool this is reasonably transparent.

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

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

The description is front-loaded with the most important usage guidance, followed by a one-sentence algorithmic note, then a clean Args block. Every line adds actionable 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?

The description covers the full parameter surface, the retrieval mechanism, and usage context, and an output schema exists so return behavior need not be restated. The only minor gap is that it never explicitly names the exact corpus being searched, though collection, agent_handle, and memory_type strongly imply 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?

The input schema has 0% description coverage, and the description fully compensates by explaining all eight parameters. It adds concrete details like the default/max for limit, example filters for source_format, agent_handle, and memory_type, and the meaning of each filter.

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

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

The description clearly states what the tool does: find is for retrieving meaning via hybrid vector/BM25 search, distinct from grep for symbol/value lookups and from WebSearch/WebFetch for external research. It names a specific role and differentiates it from alternatives.

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 opens with explicit routing guidance: use find before WebSearch/WebFetch for research, use it before answering why/how/what-did-we-decide questions, and prefer grep for symbol/value lookups. This tells the agent exactly when to choose this tool over alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that 'Returns immediately — the daemon indexes in the background', mentions 'smart sitemap discovery and single-page fallback', and explains the filesystem ownership. However, it doesn't discuss failure handling or error cases, which is a minor gap given the richness of other disclosed traits.

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

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

The description is well-structured but slightly verbose. It opens with purpose, then usage differentiation, then behavioral details, and a clear 'Args:' section. Every sentence has value, though the sibling differentiation paragraph could be tightened. Overall it's appropriately sized and front-loaded.

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

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

For a 3-parameter tool with no annotations and an output schema, the description provides comprehensive context: purpose, usage, alternative routing, parameter semantics, and async behavior. Nothing critical is missing for an agent to call it correctly, making it highly 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 0%, so the description must compensate. It does so fully by explaining each parameter: source is an 'HTTP(S) URL', overwrite 'replace existing data', collection 'Auto-derived if empty'. This adds crucial meaning beyond the bare schema, leaving no parameter vague.

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

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

Description clearly states the tool's purpose: 'Use when you have a URL to add to the knowledge base' and explicitly distinguishes it from siblings via 'remember = a specific durable fact, ingest = a URL, learn = a distilled lesson'. It names the verb and resource precisely, leaving no ambiguity about its function.

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

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

Provides explicit guidance on when to use this tool versus alternatives: 'remember = a specific durable fact, ingest = a URL, learn = a distilled lesson' and for local files 'use register_directory + sync_all_registrations'. This clearly routes the agent to the correct sibling, leaving nothing 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 responsibility for behavioral disclosure. It covers secret/PII scrubbing, background indexing, immediate return, and the 500-character cap, which are meaningful beyond the basic 'save' semantics. It does not mention whether the operation is reversible or requires auth, but the disclosed behaviors are substantial.

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

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

The description is front-loaded with purpose and differentiation, then behavioral details, then parameter semantics. Every sentence carries distinct information and the argument list is compact and readable.

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

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

For a write tool with no annotations and minimal schema, the description covers the what, when, how, behavioral side effects, and parameters. The output schema covers return values, so nothing critical is missing for correct invocation.

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

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

Schema coverage is 0%, so the description must compensate, and it does thoroughly. It adds the 500-character constraint for lesson, explains topic as a domain tag with examples, and defines name as a user-visible slug for later reference — all meaning beyond the raw 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 ('save') and resource ('distilled lesson') and defines precisely what qualifies as a lesson versus a fact or URL. It explicitly distinguishes learn from sibling tools remember and ingest, so an agent can select it unambiguously.

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

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

The description gives explicit selection criteria: remember for durable facts, ingest for URLs, learn for distilled lessons with retrieval preference. It also provides a boundary condition — lessons over 500 characters should use remember — leaving no ambiguity about when to choose this tool.

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

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

No annotations are provided, so the description carries the full burden. The word 'see' implies a read-only operation, but the description does not explicitly state that it makes no changes, nor does it mention permissions, pagination, or failure behavior. This is adequate but not richly transparent.

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

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

The description is compact, front-loads the purpose in the first line, and then uses a concise Args section to cover both parameters. Every sentence adds value beyond the schema, and there is no redundant or filler language.

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 listing tool with an output schema, the description covers the task and parameter semantics well. It could be more complete by explicitly stating read-only behavior or noting when to prefer 'find'/'show', but nothing critical is missing for invoking the tool correctly.

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

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

The input schema has 0% description coverage and no enums, making the parameter documentation critical. The description supplies the exact allowed values for 'kind' and clearly states that 'collection' only applies to kind='documents', which is essential semantic information the schema does not provide.

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

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

The description clearly states the tool lists what is already indexed and positions it as a pre-ingestion check. It identifies the resource type (indexed items) and action (see/list), but does not explicitly differentiate from sibling tools like 'find', 'show', or 'status' that could also be used to inspect data.

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

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

The phrase 'before ingesting it again' gives a clear usage context and helps an agent know when to call this tool. It does not explicitly exclude alternatives or name when to prefer a sibling, but the intended scenario is clear enough.

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

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

With no annotations, the description carries the behavioral burden. It usefully discloses that the tool returns immediately while the daemon records the registration in the background, and that sync will happen automatically. It does not cover edge cases like duplicate registrations or missing paths, but the async return behavior is valuable context.

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

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

The description is compact and well-structured: a one-line purpose, a one-line behavioral note, and a concise parameter list. Every sentence earns its place, with no redundant or vague filler.

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

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

For a simple two-parameter registration tool, the description is largely complete: it states the purpose, the async behavior, and the meaning of each parameter. It could add preconditions like directory existence or what happens when the same directory is registered twice, but the essential invocation details are present.

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

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

Schema description coverage is 0%, so the description must explain the parameters. The Args section adds meaningful semantics: directory must be an absolute path, and collection defaults to the directory name when empty. This goes well beyond the bare schema.

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

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

The description clearly states that the tool tracks a local directory so future changes sync automatically. It identifies the resource ('local directory') and the purpose, and is easily distinguished from siblings like deregister_directory and sync_all_registrations, though it does not explicitly name them.

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

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

'Use to track a local directory so future changes sync automatically' provides clear context for when this tool applies. It does not explicitly discuss when not to use it or name alternative tools, but the purpose is stated directly enough for an agent to select it correctly.

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

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

With no annotations, the description carries the behavioral disclosure burden. It reveals meaningful traits: the daemon scrubs secrets/PII before indexing, the call returns immediately, and indexing happens in the background. It also documents overwrite semantics. However, it does not clarify what happens when overwrite is false and a document already exists, so a small behavioral gap remains.

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

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

The description is well structured and efficient: a front-loaded usage statement, a sibling differentiation line, a behavioral note, and a compact Args block. Every sentence adds value and there is no redundant filler.

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

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

Given the tool's eight parameters and absent annotations, the description covers the essential context: when to use it, how routing works, what memory_type values are valid, overwrite behavior, and the asynchronous background-indexing model. The presence of an output schema means return-value documentation is not required from the description.

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

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

Schema description coverage is 0%, so the description must compensate, and it does. The Args block explains every parameter, including collection routing based on agent_handle and the special reservation of 'lesson' for the learn tool. This fully compensates for the schema's lack of parameter descriptions.

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

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

The description opens with a precise use condition — 'Use remember when you learn something durable' — and names the specific kinds of content it handles (decision, gotcha, fact, procedure). It also explicitly contrasts remember with ingest and learn, so the agent can distinguish it from nearby siblings.

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

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

The description states clearly when to use the tool and gives direct routing guidance for alternatives: 'remember = a specific durable fact, ingest = a URL, learn = a distilled lesson that gets retrieval preference.' This removes ambiguity about tool selection.

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

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

With no annotations, the description carries the burden of behavior, and it largely delivers. It explains the conditional behavior between metadata-only and full-page text, including the special 0 value for page_number. It does not explicitly state that the operation is read-only, but 'read' and 'shows' strongly imply it, and it avoids destructive or surprising language.

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

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

The description is compact, front-loaded with the main purpose, and uses a clean Args list for parameter details. Every sentence contributes meaningful information, and the conditional behavior is laid out efficiently without redundancy.

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

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

This is a low-complexity, read-style tool with 3 parameters and an output schema. The description covers the main usage modes, the meaningful special value, and the optional collection scope. It does not discuss error handling for missing/unindexed documents, but that is not essential here given the output schema and straightforward nature of the tool.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: document_name is given a filename example, page_number is documented as 1-indexed with a special 0 meaning, and collection is identified as optional scoping. The collection parameter remains somewhat vague, but the core parameter semantics are clearly conveyed beyond the bare schema.

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

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

The description opens with a specific verb and resource ('Use to read a specific page') and immediately adds a second purpose ('check whether a document is already indexed'). This clearly distinguishes it from sibling tools like list, find, or ingest by framing it as a direct read/metadata inspection operation.

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

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

It states clear use cases: reading a specific page or checking index status. It also explains when the metadata-only behavior applies. However, it does not explicitly compare against alternatives like find or list, nor say when not to use this tool, so it falls short of full routing guidance.

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

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

No annotations are provided, so the description carries the full burden. It only says 'check how much is indexed' and gives no detail on what the tool actually reports, whether it is read-only, what shape the output takes, or any operational caveats.

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

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

The description is a single sentence that states the action, the target, and the intended use context. Every word contributes, and it is front-loaded with the core purpose.

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

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

For a parameterless status tool with an output schema present, the description provides the essential context: what to check and when to check it. It could be slightly richer about what 'how much' means (count, bytes, percentage), but it is otherwise sufficient.

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

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

The input schema has no parameters, and schema description coverage is 100%. There is nothing for the description to add about parameters, so the baseline of 4 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 action ('check') and a specific resource ('how much is indexed'), and frames it as a precondition for search or ingest. It is clear enough to be understood, though it does not explicitly distinguish itself from siblings like 'show' or '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?

The description gives clear timing guidance: use it before search or ingest. It does not mention alternatives or exclusions, but for a zero-parameter status check this is reasonable context.

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

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It does disclose a key behavior: 'Returns immediately — the daemon runs the sync in the background.' However, it does not disclose side effects, whether the operation is safe/idempotent, or what happens if the daemon is unavailable, which matters for an unannotated mutation-like operation.

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

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

The description is two sentences with no filler. The first sentence front-loads the usage condition, and the second explains the critical async behavior. Every word earns its place.

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

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

For a zero-parameter tool with an output schema and clear trigger conditions, the description is nearly complete. It covers when to call and what to expect immediately, though it could slightly improve by explicitly noting that all tracked registrations are covered or how to check sync completion via a sibling like status.

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

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

The tool has zero parameters and the schema already covers everything relevant. The description adds context about when invocation is appropriate, which is the only parameter-like information an agent needs. The baseline of 4 applies because there are no parameters requiring explanation.

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

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

The description tells the agent when to use the tool and references 'the sync' run by the daemon, which combined with the tool name makes the purpose clear. It does not explicitly restate 'sync all registrations' as an operational definition, but the trigger conditions and background behavior remove ambiguity. It is distinguished from siblings by being the only sync-oriented operation among 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?

The description gives explicit usage triggers: after registering a new directory, or when tracked files changed outside quarry's own writes. It implicitly tells the agent not to use it after quarry's own writes, but it does not explicitly name alternatives 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 provided, the description carries the full behavioral burden. It discloses the important state-changing effect ('all tools will target the selected database's daemon until changed again') and the remote-target no-op condition. This is sufficient for the tool's scope, though it does not detail 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?

The description is well-structured with a clear purpose up front, behavioral notes, and an args section. The first two sentences restate the same idea somewhat, but the organization is still efficient and easy to scan.

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-argument context-switching tool, this description covers everything an agent needs: persistent side effects, how to verify current state, the local-only constraint, and parameter semantics. The output schema covers the return value, so no additional return-value detail is necessary.

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

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

The input schema provides only a string field with no description, so the schema coverage is 0%. The description compensates by explaining the argument ('Database name'), giving concrete examples ('coding', 'work'), and explaining the special value 'default'.

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

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

The description clearly identifies the tool's function: switching the target database for all other tools. It uses a specific verb and resource ('point every other tool at a different named database') and distinguishes itself from sibling data-operation tools by describing its context-setting 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 gives practical usage context: it names the persistent effect until changed again, tells the user how to see the current target via list(kind='databases'), and explicitly states when the tool has no effect (active remote target). It does not explicitly enumerate alternatives, but the when/when-not guidance is clear.

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