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

With no annotations, the description carries the burden itself. It does disclose two useful traits beyond the schema: all endpoints become searchable documentation, and saved credentials for the host are applied automatically (a real auth-behavior detail). It says nothing about failures on an invalid spec, duplicate-import behavior, or what is returned, so the coverage is partial.

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, front-loaded with the core action and input form, then behavior. Nothing is bloated, though the middle sentence restates the product's core purpose rather than adding selection-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 write-side import tool with no annotations and no output schema, the description covers the essentials of what it does and how it authenticates, but omits return/error behavior and any duplicate or overwrite semantics. Adequate as a minimum viable definition, not 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%, so the schema already documents all six parameters including examples. The description adds no syntax or format detail beyond that, so the baseline of 3 applies; there is no compensating value here, but no harm either.

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 (import) and resource (OpenAPI/Swagger specification) plus the input form (direct JSON URL), so an agent can tell roughly what happens. However, it never distinguishes itself from the sibling docs_add_swagger, and by calling the resource 'OpenAPI/Swagger' it arguably blurs the two further.

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 guidance and no alternatives are named. The phrase 'direct JSON URL' weakly implies this is for a spec URL rather than a site crawl (docs_add_url/docs_add_sitemap), but the agent is left to infer the choice against docs_add_swagger on its own.

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 disclosure burden. It does reveal useful behavior — bounded crawl via maxPages, conversion to Markdown, local storage — but says nothing about required auth (docs_auth exists as a sibling), rate limiting, handling of existing sources, or what happens when the crawl fails partway.

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: what it does, mechanical effect, and when to use it. The purpose is front-loaded and no sentence repeats the schema or the tool name.

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

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

For a 6-parameter mutation tool with no annotations and no output schema, the description covers the main flow adequately but omits permissions, storage location, deduplication/overwrite behavior and post-crawl verification. Those gaps are meaningful for an agent deciding how to sequence this with docs_auth and docs_preview.

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 every parameter including maxPages, urlPattern, name, sourceId and description is already documented in the schema. The description adds only the implicit note that maxPages bounds the crawl, 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+resource ('Crawl an entire documentation site from its sitemap.xml') and explains the pipeline (scrape, convert to Markdown, store locally), which naturally distinguishes it from the URL- and spec-based siblings. It never names an alternative outright, so sibling differentiation is inferred rather than stated.

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 for adding complete doc sites' gives the intended context, but there is no when-not guidance and no mention of docs_add_url, docs_add_swagger or docs_add_openapi, which an agent must choose between for other source types. Usage is implied by the sitemap framing rather than explicitly scoped.

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 auto-detection of the spec URL, which is genuinely useful behavior, but says nothing about side effects, idempotency, what happens if detection fails, whether an existing source is overwritten, or permission/auth requirements. For a mutation/import tool, this is a significant gap.

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, zero filler. The primary action is front-loaded, the auto-detection behavior follows, and the usage cue closes. 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 mutation tool with no annotations and no output schema, the description is thin. It covers purpose, the detection behavior, and a usage hint, but omits side effects, failure handling, and auth needs. Adequate to trigger the right call, not enough to predict outcomes.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters with examples and optionality. The description adds no parameter-level detail beyond what the schema provides, 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?

States a specific verb+resource: 'Import documentation from a Swagger UI page.' This clearly distinguishes it from siblings like docs_add_url, docs_add_sitemap, and docs_add_openapi, which target other source types. It could be sharper about what 'import' produces (a source? a doc set?) but the purpose is unambiguous.

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

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

Gives an implied usage condition: 'Use this when you have a Swagger UI URL like /swagger or /api-docs.' This helps distinguish it from docs_add_openapi (raw spec), but it does not explicitly state when NOT to use it or name the alternative for when you already have the spec file. The routing 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, the description carries the full behavioral burden. It usefully discloses crawling behavior, Playwright/JS-rendering support, and content detection, but says nothing about whether docs are persisted as a source, auth requirements, rate limits, or failure behavior for an add/mutation 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?

Compact and front-loaded: purpose first, then feature/parameter notes. Each sentence carries some weight, though the feature list is somewhat marketing-flavored and could be tightened.

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

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

For a 9-parameter mutation tool with no annotations and no output schema, the description covers the headline behavior but omits persistence semantics, auth, and result shape. Adequate but incomplete for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters, and the baseline is 3. The description largely restates schema facts (recursive crawling, Playwright for JS-rendered sites) rather than adding new meaning beyond what the input schema provides.

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

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

The description states a specific verb and resource: 'Add documentation from a URL.' It is clear what the tool does, but it does not differentiate itself from siblings like docs_add_sitemap, docs_add_openapi, and docs_add_swagger, which all also ingest docs from a URL source. Clear but not sibling-aware.

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 only guidance is 'Use recursive=true to crawl multiple pages,' which is a parameter hint rather than when-to-use guidance. Nothing says when to pick this tool over docs_add_sitemap/docs_add_openapi, nor any prerequisites or exclusions.

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

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

No annotations are provided, so the description carries the full burden. It adds one valuable behavioral fact — stored credentials are automatically applied during API fetching — but omits key traits for a mutation tool: whether 'remove' is irreversible, where credentials are stored, what 'get' exposes, and any error behavior for missing hosts.

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 the core purpose front-loaded and the action inventory second. No filler, and the automatic-use fact is placed last where it functions as context rather than definition; the parenthetical action glosses are slightly redundant but cheap.

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

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

For a five-parameter tool with no annotations and no output schema, the description covers purpose and the auto-use behavior but leaves the return shape of 'list'/'get' and the destructive consequences of 'remove' unaddressed. It is workable to invoke correctly but not complete.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, including per-action requirements (host/type/value for add, host for remove/get). The description's action list is largely redundant with the schema's own action enumeration, adding only the 'save/show/delete' glosses, so 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-and-resource purpose ('Manage authentication credentials for documentation sources') and enumerates the four supported actions with parenthetical glosses, so an agent knows exactly what the tool covers. It distinguishes itself from the content-oriented siblings (docs_add_swagger, docs_search, etc.) by domain, though it never explicitly names a sibling it is not.

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

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

The closing line, 'Credentials are automatically used when fetching APIs,' implies when this tool matters (before fetching a host that needs auth), which is genuinely useful context. However, there is no explicit when-to-use versus when-not, no statement of prerequisites or ordering relative to the fetch tools, so usage remains inferred rather than 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. It usefully discloses that sources are stored locally and what each entry contains (names, page counts, descriptions), implying a safe read. It says nothing about pagination, ordering, or whether an empty result is possible.

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 with the core action front-loaded and the return shape immediately after. 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?

No output schema or annotations exist, so the description must convey enough to call and interpret the tool. It names the returned fields well, but leaves minor gaps around result size and ordering that an agent might want to know.

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 misinterpret and the description has no syntax to document. Per the baseline for zero-param tools, a 4 is appropriate.

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

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

States a specific verb (List) and resource (available documentation sources stored locally), which cleanly separates it from siblings like docs_search and docs_read. It does not explicitly name a sibling to disambiguate against, so it falls just short of a 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?

Usage is implied: enumerating local sources is naturally the discovery step before docs_read or docs_search. However, the description never states when to prefer it over siblings or any prerequisites, so the guidance remains implicit 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 must carry the full burden. It discloses the key behavioral trait ('without saving') and what is shown ('extracted content, metadata, and discovered links'), but does not mention potential side effects (e.g., network requests, rate limits) or authentication requirements. It covers the core non-destructive nature but lacks other operational details.

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

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

Two sentences, front-loaded with the core purpose and usage guidance. No unnecessary words; every sentence earns its place.

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

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

Given no annotations, no output schema, and a simple 4-parameter tool, the description covers purpose, usage, and basic output (content, metadata, links). It could be more complete by noting any limitations (e.g., does not follow redirects, may require auth), but it is sufficient for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal parameter-specific meaning beyond the schema, but the tool's purpose implies the parameters are used for preview configuration. Baseline 3, but the 'without saving' context slightly clarifies that parameters like 'usePlaywright' affect the preview only, not stored 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?

The description clearly states a specific verb ('Preview') and resource ('scraped content'), and distinguishes it from the sibling 'docs_add_url' by emphasizing 'without saving' and 'test scraping before adding docs'.

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

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

It gives explicit when-to-use guidance: 'Use this to test scraping before adding docs.' This directly names the alternative action (adding docs) and the condition (testing).

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

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

No annotations are provided, so the description carries the full burden. It discloses the two operating modes (read one page vs. list all), but says nothing about auth requirements (despite a docs_auth sibling), error behavior for invalid sourceId/pagePath, or response shape. Read-only nature is only implied.

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, zero waste, with the core action front-loaded and the conditional mode immediately after.

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 is the only behavioral source. It covers the main mechanics but omits authentication prerequisites and result shape, which are material for a docs retrieval tool in a suite containing docs_auth.

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 each parameter's description already explains its role, including the omitted-pagePath behavior, so the schema does the heavy lifting. The description repeats this without adding format or validation detail (e.g., what a valid sourceId looks like beyond examples).

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

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

States a specific verb+resource ('Read a specific documentation page') and discloses the dual-mode behavior when pagePath is omitted. It does not explicitly distinguish itself from siblings like docs_list or docs_search, which could plausibly retrieve the same content.

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

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

The description gives a clear conditional ('If pagePath is omitted, lists all pages'), which implies usage but doesn't state when to prefer this over docs_list, docs_search, or docs_preview for retrieval.

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 disclose the two most important traits: the operation is destructive and it cascades to 'all its pages', plus a confirmation gate. It omits whether deletion is permanent/irreversible and whether elevated permissions are needed, 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?

Two short sentences, zero filler, with the destructive scope front-loaded before the confirmation caveat. Nothing is wasted and nothing essential is 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 destructive, two-parameter tool with no annotations and no output schema, the description covers scope, cascade effect, and the confirmation requirement. Gaps remain around reversibility and authorization, which an agent would need before committing to a 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?

Schema description coverage is 100% (confirm and sourceId are both documented, including a pointer to docs_list), so the baseline is 3. The description's 'Requires confirmation' adds only a faint echo of the confirm parameter and no new syntax or format detail.

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

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

States a specific verb (Remove) and resource (a documentation source) plus its blast radius ('and all its pages'), which clearly separates it from docs_update or the docs_add_* family. It stops short of naming a sibling as an alternative, 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?

'Requires confirmation' implies the preconditions for invoking the tool, and the intent to delete a source is self-evident. However, there is no explicit when-to-use versus docs_update, no warning about when deletion is inappropriate, and no statement of the required permission level.

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 the return shape ('matching pages with snippets'), which is genuinely useful since there is no output schema. It says nothing about result ranking, whether all sources are searched by default, pagination, or permissions, leaving meaningful behavioral gaps.

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

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

The first two sentences are front-loaded and informative, but the third sentence ('Use this to find relevant documentation') is circular filler that duplicates the opening. The definition is short but not fully waste-free.

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 search tool with no annotations and no output schema, the description covers the basics (what it searches, what it returns) but omits result ordering, default source scope, and any auth/permission notes. Adequate as a minimum-viable definition, not 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% (query, limit, sourceId all documented), so the schema already does the heavy lifting and a baseline 3 is appropriate. The phrase 'across all local documentation' implicitly clarifies that sourceId narrows scope rather than being required, but adds no further syntax or format detail.

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

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

States a specific verb and resource ('Search across all local documentation') and notes the scope ('local'), which separates it from remote/URL-based ingestion siblings. However, it never names or differentiates itself from the closest siblings such as docs_list or docs_read, so an agent must infer the boundary.

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 only guidance is 'Use this to find relevant documentation,' which simply restates the purpose rather than telling the agent when to choose this over docs_list or docs_read. No conditions, prerequisites, or alternatives are given.

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

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

With no annotations, the description carries the full burden. It usefully discloses that the operation re-scrapes remote content, detects changes, and returns a diff summary, which implies a mutating, network-dependent write. It does not say whether existing docs are overwritten or preserved, whether the change is reversible, or what auth/permission is required.

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, zero filler, and the core action and scope are front-loaded before the diff-summary note. Every sentence carries information an 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 mutating tool with no annotations and no output schema, the description does provide the one important return signal (diff summary) and the scoping behavior. It still omits the safety/permission and overwrite semantics an agent should know before triggering a re-scrape of an entire source.

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 already documented, including the pagePath-omitted behavior. The description adds no syntax, format, or constraint detail beyond what the schema states, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Update/refresh existing documentation by re-scraping') plus the two supported scopes (whole source vs single page). It is distinguishable from docs_add_url/add_sitemap by the re-scrape framing, but it never names a sibling tool, so differentiation is implicit rather than explicit.

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

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

'Can update an entire source or a single page' implies when each mode applies via pagePath, but there is no explicit when-to-use guidance, no statement of prerequisites (e.g., that sourceId must come from docs_list), and no mention of when to prefer re-adding via docs_add_url instead.

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