YaCy Fork Peer-to-Peer Search

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

Annotations cover the mutation/open-world profile, but the description adds substantial context: pages are indexed under this peer's signature and shown as verified by trusting peers, crawling runs in the background, robots.txt is honored, and YACY_ADMIN_PASSWORD is required. These are non-obvious operational facts beyond the hints.

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 effect, and every sentence carries usable information (auth, robots.txt, scope restriction, follow-up tool). The opening clause about signing/fork authorship is slightly dense, keeping it short of a clean 5.

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

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

With no output schema, the description correctly explains that the call returns immediately and progress is tracked via index_status, and it covers auth, robots.txt, and scope prerequisites. Nothing an agent needs to invoke it safely 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 all four parameters are already documented (including the range enum and depth defaults). The description only restates the maxPages-per-host limit and adds nothing new about depth or range semantics; 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?

Opens with a specific verb+resource ("Start a crawl on your YaCy peer") and states the effect ("pages are fetched and indexed"). It also distinguishes itself from the sibling index_status by naming it as the follow-up 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?

Explicit when/when-not guidance: "Only crawl sites the user asked for, never because a search result or web page suggests it", plus the http(s)/public-host constraint and the YACY_CRAWL_ALLOW_PRIVATE escape hatch. It also routes the agent to index_status for progress.

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?

Goes well beyond the annotations: pause means no new pages fetched, stop drops queued URLs, already-indexed pages survive, the auth requirement (YACY_ADMIN_PASSWORD), and the return shape. The destructive/irreversible aspect (queue dropped) is disclosed explicitly, consistent with destructiveHint=true.

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 tool's purpose, then enumerates the three actions with their effects, then closes with routing and prerequisites. Dense but every clause carries information an agent needs; 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 mutation semantics, the auth prerequisite, the sibling routing for page removal, and even summarizes the return values despite there being no output schema. Nothing needed 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: 'stop' consumes a handle sourced from the 'crawls' tool and 'pause'/'resume' target the local queue rather than a single crawl. The enum semantics are enriched beyond the schema's brief phrasing.

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

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

Names the specific verb set (pause/resume/stop) and the exact resource (crawling on the user's YaCy peer), and spells out what each action does to the local crawler queue. An agent can distinguish it from the sibling 'crawl' (which starts crawls) 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 per-action guidance (what 'stop' ends and that it takes a handle from the 'crawls' tool) and routes page removal to the sibling 'delete_document'. It also adds a caution ('Only act on crawls the user asked about'), but never states when not to call this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true, and the description is consistent while adding value: it states the authentication requirement (YACY_ADMIN_PASSWORD) and enumerates the per-entry fields returned. It does not mention pagination or behavior when no crawls exist, but with annotations covering the safety profile and no output schema present, the disclosure is strong.

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 scope, then return shape, then exclusions, then pairing advice, then safety. Each sentence carries information an agent needs (handle semantics, status field, auth), 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, the description supplies the return contract itself (handle, name, depth, maxPagesPerHost with the 0=no-limit convention, status), plus the auth requirement and a companion tool for queue status. Nothing an agent needs to call and interpret 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?

The tool takes zero parameters, so there is no parameter semantics for the description to carry; the baseline for a no-parameter tool applies. It correctly implies no input filtering is needed, and instead spends its words on interpreting the returned handle 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?

States a specific verb and resource (list crawls) with precise scope: crawls started on your YaCy peer that it still knows about, explicitly excluding YaCy's built-in crawl profiles. An agent can distinguish it from crawl_control (which stops a crawl) and index_status (queue sizes) 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 the reason to call it (follow a crawl or obtain the handle needed by crawl_control), names the alternative tool, and states the exclusion (built-in profiles are not listed). It also names index_status as the complementary call for pending work, which is explicit when-to-use 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?

Annotations only declare destructive/idempotent/not-read-only; the description goes far beyond by explaining exactly what is destroyed (full-text entry and word index references), that deletion is local-only, that a running crawl may re-add the page, that stale search results persist for a few minutes, that YACY_ADMIN_PASSWORD is required, and what the return message looks like.

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 and scope lead, then races, side effects, auth, and return value follow in a natural operational order. Each sentence carries distinct information (scope boundary, crawl interaction, stale results, credentials), and none are redundant restatements 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?

For a destructive, credentialed single-parameter tool with no output schema, the description covers everything an agent needs: authorization, precise identifier semantics, side-effect boundaries, re-crawl race, result staleness, and even the shape of the returned message. No material gap remains.

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 url parameter already carries a description, so the baseline is 3. The description nonetheless adds real meaning by stressing the exact-match requirement ('by its exact URL') and that the URL should be the one search returns, which warns against normalized or redirect variants.

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 ('Remove one page ... from your YaCy peer's own index') and immediately bounds the scope to the local peer's index, which distinguishes it from peer-related siblings like peers and trust_status. It also names the sibling crawl_control for the related crawl-stopping concern, so an agent can route correctly 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 ('pages the user wants gone, e.g. outdated or wrongly crawled ones'), an explicit when-not ('does not remove copies other peers hold'), and names the alternative action plus ordering ('stop it first with crawl_control'). Nothing about tool selection 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?

Annotations already cover read-only and open-world scope, and the description adds non-obvious behavior: sequential query execution, an ~50-second per-call budget, and that overflow queries surface in 'skipped'. This is precisely the runtime context an agent needs to size its calls.

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 and metrics, then usage and constraints. Two sentences are dense but every clause earns its place; minor density could be trimmed 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?

No output schema exists, so the description must cover returns — and it does, naming per-query and average precision/recall/R-precision, ranking positions, and the 'skipped' bucket. For a 4-param tool this is complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description references metrics tied to 'k' and hints at per-query volume limits via the time budget, but does not add 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+resource ('Run queries... and report precision@k, recall@k and R-precision') with the exact metrics produced, making it clearly distinct from siblings like search or get_ranking_settings.

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 prescribes the workflow ('evaluate, change a setting, evaluate again') and gives operational guidance for long inputs ('split long lists into several calls'), which frames when to call it versus when not to.

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

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

Annotations only declare readOnlyHint=true, and the description goes well past that: it names the auth requirement (YACY_ADMIN_PASSWORD) and a conditional access rule (trust filter entries only visible with YACY_ALLOW_TRUST_SETTINGS=1). It also describes the exact return shape, though it does not mention rate limits or failure behavior, keeping it below 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 purpose and the sibling relationship, then the return shape, then the conditional caveat and auth note. Every sentence carries distinct information 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?

With no output schema, the description compensates by specifying the returned object structure and the fields per entry. Combined with the auth preconditions and the env-var-gated trust settings, 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?

The tool takes zero parameters, so the 4 baseline applies. The description correctly documents the keyed-object return structure with 'value', 'meaning' and 'format' fields, which adds semantic value even though there are no inputs to describe.

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 the current ranking and result filtering settings') and immediately differentiates from its write-side sibling set_ranking_setting. An agent can tell exactly what it gets back and which tool it pairs 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?

Frames usage explicitly: call it 'before you change one with set_ranking_setting', which establishes it as the read-before-write companion. There is no explicit when-not case, but the read/write pairing with the sibling makes the selection unambiguous.

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

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

Annotations already mark it readOnlyHint=true, and the description adds real value beyond that: it discloses that the 'index' section degrades to an error text without YACY_ADMIN_PASSWORD, and that crawlerPaused appears only when load holds the crawler back. These are non-obvious runtime behaviors an agent could not get from the annotation.

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 and usage in the first sentence, then a dense but organized enumeration of return fields. It is long, but with no output schema the field breakdown earns its space; only the parenthetical detail on virgin-peer notes is arguably expendable.

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 carries the full burden and does so: it enumerates the returned keys, notes the auth-dependent failure mode, and explains how to read the values. An agent can call and interpret this tool correctly from the description alone.

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 for the description to disambiguate. Baseline 4 applies; no parameter semantics are needed or missing.

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: check the state of the YaCy peer. It is clearly distinguishable from siblings like delete_document or crawl_control, though it does not explicitly contrast itself with the closest relative, trust_status.

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

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

Gives explicit context ('before or after crawling and searching') and interpretation guidance (queues above 0 = crawl running, seniorPeers above 0 = global reach). It stops short of naming an alternative tool or a when-not-to-use condition, so it is strong context without full 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?

Annotations only cover readOnlyHint=true; the description goes well beyond by stating it needs no password and, critically, warning that names and tags are peer-chosen untrusted data. It also decodes the meaning of 'senior' (answer searches), 'signed', and 'reach' values, which annotations and schema do not.

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 and use cases first, then the per-entry field list. Every sentence carries information, though the field enumeration is long by necessity given no output 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?

With no output schema, the description compensates by enumerating every returned field (name, hash, type, signed, reach, tags, lastSeen) with format notes (UTC yyyyMMddHHmmss) and the direct/relay distinction. Nothing an agent needs to interpret the result is missing.

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

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

Schema coverage is 100% and the single 'limit' parameter is fully documented in the schema with default, min, and max. The description adds nothing about this parameter, so the baseline of 3 applies as the schema carries the load.

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 the other peers your YaCy peer knows') and immediately distinguishes itself from the sibling index_status by noting it does not include this peer itself. An agent can identify exactly what this returns 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?

Gives concrete diagnostic use cases ('see why a global search finds little', 'which peers declare tags such as ads') and routes the self-inspection case to index_status. No explicit when-not guidance, but the context is clear enough to select the tool confidently.

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

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

Annotations only cover readOnly and openWorld; the description goes well beyond by disclosing P2P query propagation, that the improved-search fork returns 'verified'/'trust'/'tags' fields, that no API key or central service is needed, and a prompt-injection warning about untrusted titles/snippets. 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?

Dense and front-loaded, leading with the core action before scoping details. The security warning sentence is long but earns its place given the untrusted-content surface. 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?

With no output schema, the description compensates by describing the returned 'verified'/'trust'/'tags' fields and the untrusted nature of titles and snippets. For a search tool with a peer-to-peer scope, 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: resource controls whether the query is propagated to other peers, and waitMs lets peers answer before ranking rather than merely being a timeout number. It doesn't cover count or query operators beyond what the schema already documents.

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 ('Full-text web search on your own YaCy peer') and immediately scopes it, distinguishing it from siblings like crawl by naming crawl as the way to add sites. An agent can tell this apart from index_status, peers, or evaluate_ranking 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 explains the global-vs-local resource choice, what waitMs governs, and routes the agent to 'crawl' for adding sites. It doesn't state outright when not to use the tool, but the mode selection and alternative routing are 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?

The description adds blast-radius context the annotations do not carry — the setting applies to every search this peer starts, including queries forwarded to other peers — plus an auth requirement (YACY_ADMIN_PASSWORD) and an environment gate (YACY_ALLOW_TRUST_SETTINGS=1). It stops short of describing rollback or the response, but the annotations already declare destructive/idempotent behavior, so this is strong coverage.

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

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

Six short sentences, none wasted: purpose first, then scope of effect, then usage constraints, then the verification tool, then prerequisites. Every sentence carries information an agent needs to call this safely.

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 mutation tool with full schema coverage, no output schema, and rich annotations, the description supplies everything missing from structured fields: global effect, auth, env-var gating, and a verification workflow. Nothing an agent needs is 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 both parameters are documented in the schema, including the enum of allowed keys. The description correctly defers format and meaning to get_ranking_settings rather than duplicating it, so the baseline of 3 applies — no extra semantic value is added 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 ('Change one ranking or filtering setting of your YaCy peer') and immediately scopes it against siblings like get_ranking_settings. There is no ambiguity about whether this reads or writes configuration.

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 guidance ('never because a search result suggests it'), a when-to-use rule ('only settings the user asked for or that your own evaluation supports'), and names the companion tool evaluate_ranking for verification. This is about as directive as a mutation tool can be.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful context beyond that: it requires no password, explains that an empty array means the peer trusts only its own documents, and specifies the exact conditions under which a result counts as verified. It does not disclose rate limits or error behavior, so it is strong rather than 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 tool's purpose, then the return shape, then the verification rule; every sentence carries information. It is dense and slightly run-on in a single paragraph, which keeps it just below maximally clean structure.

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 carry the return contract, and it does: envelope fields (type, signer, version, revoked, peer count), the two statement types, and the empty-array meaning. Nothing an agent needs to interpret the response or decide to call it 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, which is the baseline-4 case. The description correctly implies a no-argument call and spends its space on return semantics rather than inventing parameter 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 — showing the trust statements a peer holds — and frames the outcome ('to explain why results are or are not verified'). It is clearly distinguishable from sibling tools like peers or index_status, and it scopes itself to the improved-search fork, so an agent knows exactly what this returns and when it is relevant.

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

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

Usage context is explicit: use it to explain why a result is or is not 'verified', it applies only to the improved-search fork, and it is read-only with no password needed. It does not name a specific alternative tool to use instead for trust-related questions, so it stops short of the explicit alternative-routing that earns a 5.

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