Taproot: AT Protocol MCP

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

Annotations only cover readOnly/openWorld; the description adds the non-obvious behaviors that matter — server-side scanning, exact:false for very large collections, lower-bound counts, and the accumulate-cursor contract. This is exactly the context an agent needs to interpret a non-exact result.

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

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

Purpose and the cursor caveat are front-loaded, and every sentence earns its place. However, the second and third sentences are run-ons with missing spaces after commas ('cursor,call again'), which slightly hurts readability.

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 an output schema present, the description needn't cover return shape, and it still warns about exact:false, which the schema alone may not disambiguate. Nothing needed to call this correctly is missing.

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

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

Schema coverage is 100% and the schema already documents repo/cursor/collection. The description nonetheless adds real semantic value: the new count covers records AFTER the cursor and must be added to the previous total, which is the key usage contract for cursor.

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+scope: 'Count the total records in an account's collection', with a concrete example. It is clearly distinguishable from siblings like list_records (returns rows) and count_repos_by_collection (counts repos, not records).

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

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

Explains the operative path: use it instead of paging manually, and when a capped result arrives, call again with the cursor and ADD the counts. It gives clear context for the cursor workflow but never names an alternative tool or when not to use this one.

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 readOnly/openWorld; the description adds real behavior: no per-account handle resolution, so it's cheap, exact totals for typical collections, exact:false + cursor for very large ones, and relay-served by default. These are non-obvious traits an agent needs.

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

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

Front-loaded with the purpose and example, then paging behavior, then relay notes. Efficient overall, though some comma-spliced clauses ('cursor,call again') are dense and slightly hard to parse.

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 an output schema present, return values need not be explained, and the description still covers the exact:false shape, paging, and relay default. Complete enough for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: relay defaults to the public Bluesky relay and cursor counts must be summed rather than overwritten. Useful additive context.

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: counting accounts that publish a given collection across the network, with a concrete example query. Clearly distinguishes it from siblings like count_records and list_repos_by_collection.

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

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

Explains the paging protocol (exact:false + cursor, call again and ADD counts, referencing count_records) and the relay override condition. Gives clear context but does not state exclusions vs. list_repos_by_collection beyond the 'count' framing.

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 openWorldHint=true, so the safety and network-fetch profile is covered. The description adds meaningful scope context (works for any PDS, not just Bluesky) but doesn't disclose fetch behavior, latency, or failure modes for an unresolvable origin.

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

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

Two tight sentences, front-loaded with the resource and its return fields, followed by scope and input format. No filler; each clause carries information.

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

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

An output schema exists, so return values need not be spelled out, and the read-only/open-world annotations cover behavior. For a one-parameter read tool the description is sufficient, with only the sibling-routing guidance missing.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema ('A PDS origin URL, e.g. https://pds.example.com'). The description restates the same input format without adding new meaning, so this is the baseline case where the schema does the heavy lifting.

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

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

States a specific verb (Describe) and resource (Personal Data Server) and enumerates exactly what is returned: DID, invite requirement, handle domains, ToS/contact links. The scope note 'Works for any PDS, not just Bluesky' sharpens it, though it doesn't explicitly distinguish itself from siblings like get_pds_directory_info or get_did_document.

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

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

Usage is implied by the purpose (given a PDS origin, describe that server), but there is no explicit when-to-use, when-not, or named-alternative guidance versus related tools such as get_pds_directory_info. Adequate minimum but leaves routing 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 declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds useful behavioral context by identifying the PLC audit log as the source and listing the categories of history returned.

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 tightly written sentences front-load the tool's purpose, scope, and input. Every phrase carries useful 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?

With read-only annotations, a complete input schema, and an output schema present, the description provides everything needed to call the tool correctly. It covers the data source, returned history categories, account-type restriction, and accepted input forms.

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

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

Schema description coverage is 100%, and the one parameter is fully described in the schema. The description says 'Input is a handle or DID,' which is essentially the same information, so it adds little beyond the schema baseline.

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

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

States a specific verb+resource (account history) and enumerates the exact contents: handle changes, PDS migrations, signing-key rotations, and creation time. It also scopes the tool to did:plc accounts, which helps distinguish it from DID-document or resolver 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?

Clearly establishes when the tool applies via 'did:plc accounts only' and explicitly excludes did:web accounts. It does not name an alternative sibling tool, so it falls short of full when/when-not/alternatives 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 already declare readOnlyHint=true and openWorldHint=true, so the operator knows it is a non-mutating, network-facing read. The description adds that the result includes a canonical PDS getRecord URL, which implies a network fetch, but says nothing about auth requirements, failure modes, or rate limits.

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

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

Content is front-loaded into a single sentence that leads with the transformation and then the usage cue. It is appropriately sized, marred only by a minor typo ('links,a') and slight run-on 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?

With an output schema present, the description need not enumerate return fields, and it usefully previews the three link kinds. Combined with the annotations, an agent has enough to call this correctly; only auth/error behavior is unaddressed.

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

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

Schema coverage is 100% with one parameter, and the schema already documents 'at:// URI, handle, or DID'. The description repeats the same accepted input forms without adding syntax or format detail, so it stays at the baseline for fully-covered schemas.

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 ('Turn ... into') and a precise set of outputs: a shareable web link, a Bluesky/Blacksky app URL, and the canonical PDS getRecord URL. This separates it from sibling read tools like get_record or resolve, though it never names those siblings explicitly.

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 a clear trigger condition — 'Use when the user wants a clickable/pasteable link' — which is a meaningful when-to-use cue. It does not, however, state when NOT to use it or name alternative tools such as resolve or get_record for non-link needs.

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 readOnly and openWorld, so the description focuses on added context: results are aggregate counts only, each category carries a `source` string, and the data comes from the Constellation backlink index. It stops short of describing shape/pagination, but the output schema covers return values, so this is solid added value.

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

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

Front-loads the resource and its output shape, then routes to the alternative. Efficient overall, though the comma-spliced category list makes the first sentence denser than necessary.

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

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

For a single-param aggregate-read tool with an output schema, the description covers what is returned (counts per category), the target formats, and the sibling handoff. Nothing an agent needs to select and invoke it correctly is missing.

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

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

Schema coverage is 100% and the schema already documents `target` as 'A record at:// URI or a DID.' The description restates the same accepted formats (at:// URI or DID) without adding syntax, constraints, or examples beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific resource (backlink index) with the exact categories it aggregates (likes, reposts, quotes, replies, follows) and clarifies it returns COUNTS, which is the key differentiator. It also names the sibling list_backlink_records so an agent can immediately tell the two apart.

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 gives the when-to-use-this vs. when-to-use-alternative rule: use this for aggregate counts, and 'to list the actual records and their author DIDs for one category... call list_backlink_records with that source.' The switching condition and handoff parameter are spelled out.

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

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

Annotations already cover read-only and open-world safety. The description adds genuinely useful behavior the annotations do not: the metadata comes from a best-effort HEAD request, content-type and size may be approximate, and it never returns bytes.

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

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

Three tight sentences, each earning its place: what is fetched, what is returned, and when to use it. The most decision-relevant constraint ('never the bytes') is front-loaded.

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

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

An output schema exists, so return values need not be spelled out, yet the description still clarifies the key output distinction (URL, not bytes). With annotations covering safety and the schema covering inputs, 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 both parameters are already documented. The description restates them ('the owning repo (handle or DID) and the blob CID') without adding format or syntax beyond the schema, making this baseline-level contribution.

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

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

States a specific verb and resource ('Get metadata for a single blob') and immediately scopes what is returned ('the URL, never the bytes'). The word 'single' cleanly distinguishes it from the sibling list_blobs.

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

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

Explicitly says when to use it: 'to turn a blob ref (CID) found in a record into a downloadable link and learn what it is.' It gives clear context but never names a sibling alternative or an exclusion, so it stops short of the top tier.

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 the safety profile (readOnlyHint, openWorldHint), so the bar is lower. The description adds useful detail about what the document contains (aliases, services, verification methods) and that it works for did:web, but it omits operational traits like authentication requirements, rate limits, or error behavior that could further aid the agent.

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, well-structured sentence that front-loads the core action and then efficiently packs scope, sibling comparison, and input format. Every clause earns its place with no redundancy.

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

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

Given the low complexity (one parameter), the presence of annotations covering safety, and an output schema that handles return values, the description is nearly complete. The only minor gap is the absence of any note on error conditions or authentication, which could be helpful but is not critical here.

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

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

Schema description coverage is 100% and the single parameter is fully documented as 'A handle or DID'. The description simply restates 'Input is a handle or DID' without adding format hints or constraints beyond the schema, so it meets the baseline without exceeding it.

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

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

States a specific verb (Fetch) and resource (raw DID document) and explicitly distinguishes itself from sibling get_profile, noting it is broader. The scope is further clarified by listing the content categories (aliases, services, verification methods) and supported DID types (did:web).

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 clear contextual guidance by contrasting with get_profile ('Broader than get_profile') and mentioning a use case (did:web accounts), which implies when to use this tool over the profile-specific one. However, it does not explicitly state when NOT to use it or offer a direct alternative for narrow needs, leaving some 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 declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond them: that this is the cheapest/lightweight option and avoids downloading data, which tells the agent about cost. It stops short of noting rate limits or response latency, so it is not a 5.

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

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

Three sentences, front-loaded with the core purpose, then the discriminating use case, then the sibling contrast. Efficient overall, though the final 'Input is a handle or DID' sentence is redundant with the schema and could be dropped.

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?

An output schema exists, so return values need not be explained, and the description still helpfully previews the CID/revision payload. For a single-param read tool, nothing an agent needs to call it correctly or route away from get_repo_status is missing.

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

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

Schema description coverage is 100% and the single 'repo' param is already documented as 'A handle or DID.' The description's 'Input is a handle or DID' simply restates the schema, adding no syntax or format detail. 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 ('the current head commit of an account's repository') and names exactly what it returns (commit CID and revision). It explicitly contrasts itself with the sibling get_repo_status, so an agent can distinguish the two without opening either schema.

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

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

Provides a clear when-to-use condition ('the cheapest way to fingerprint a repo or detect whether it changed since you last looked, without downloading data') and names the alternative (get_repo_status) plus the discriminator (it has the rev but not the commit CID). Routing is 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 declare readOnlyHint and openWorldHint, so with that lower bar the description still adds genuine value: it discloses that the data is cached and best-effort, that counts are approximate, and that a 'last-checked' timestamp exists, which tells the agent the data may be stale. It doesn't mention refresh behavior or failure modes when a hostname is unknown.

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

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

Two tight sentences, fields front-loaded, no filler. The 'Input is the PDS hostname' clause partially restates what the schema and the parameter's own example already say, which is minor redundancy but not bloat.

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?

An output schema exists, so return-value explanation is not strictly required, yet the description still names the payload contents helpfully. Combined with the caching caveat and a 100%-covered single parameter, an agent has enough to call this correctly; only the sibling-differentiation gap keeps it from a 5.

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

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

Schema description coverage is 100% for the single hostname parameter and the description merely repeats the same example (pds.example.com). No additional meaning, format constraints, or edge-case handling is added beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('cached health card for a PDS from pds.directory') and enumerates the returned fields (version, DID, user count, reachability, last-checked, domains, relays). It is clear what the tool does, though it never distinguishes itself from the sibling describe_pds, which an agent will likely confuse it with.

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

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

The description explains what the input is but gives no when-to-use guidance, no prerequisites, and no exclusions. With a sibling named describe_pds that sounds functionally adjacent, the absence of any routing cue ('use describe_pds instead when X') leaves the agent to guess between them.

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 openWorldHint=true, so the safety profile is covered. The description adds only the field list, which the output schema already carries; it says nothing about auth requirements, rate limits, or behavior on unknown handles. This is adequate but not additive.

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, zero waste, with the resource and return contents front-loaded before the input note. Nothing is padded or repeated unnecessarily.

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?

An output schema exists, so return values need not be explained, and the schema fully covers parameters. The remaining gap is routing among similar lookup tools, which the description never addresses, but for a simple read 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?

Schema description coverage is 100%, so the schema fully documents both actor and include. The description merely echoes the actor input format and never mentions the optional 'include' enrichments, so it adds nothing beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Get an account's repository overview') and enumerates the returned fields (handle, DID, PDS, collections), so the agent knows exactly what it yields. It does not differentiate from near-siblings like get_did_document, get_repo_status, or resolve, which a crowded sibling list makes valuable.

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?

'Input is a handle or DID' restates the actor parameter rather than saying when to choose this tool over get_did_document, resolve, or verify_handle. No prerequisites, exclusions, or alternative-routing guidance is given despite many overlapping siblings.

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 openWorldHint=true, so the safety profile is covered. The description adds that the call resolves identity and requires a fully-qualified URI, but says nothing about failure modes (missing record, unresolvable DID) or rate limits. Adds light context above the annotations, not rich 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?

Two tight sentences with the addressing requirement front-loaded and the return summary second. No filler, no restatement of the name or title.

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?

An output schema exists, so return values needn't be spelled out, and the annotations cover the safety profile. The one gap is that the description never hints at the available 'include' enrichments, which is the only non-obvious invocation choice for this tool.

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

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

Schema coverage is 100% and both the uri format and the 'include' enrichments (schema/backlinks/profile) are fully documented in the schema itself. The description only restates the URI requirement and never mentions the 'include' parameter, so it adds little beyond the schema baseline.

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

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

States a specific verb (fetch) and resource (a single record) and pins down the identifier form required to address it. Against siblings like list_records, get_backlinks, and get_profile, an agent can immediately tell this is the single-record-by-URI retrieval 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?

The description gives a hard precondition ('must include collection and rkey'), which is useful, but it never states when to choose this over list_records or when to prefer get_backlinks/get_profile for the enriched data. Usage is only implied by the singular 'single record'.

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 establish readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-obvious behavioral context beyond the annotations: the data is cached and best-effort, alerting the agent that counts may be stale or approximate.

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, zero waste, and the identity of the resource and its contents are front-loaded before the caching caveat. Nothing is repeated from the schema beyond a brief echo of the example.

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 an output schema present, the description need not detail return values, and annotations cover read-only behavior. It is complete enough for a single-parameter read tool, missing only explicit sibling routing to get_pds_directory_info.

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 hostname parameter is already documented with the same bsky.network example in the schema, so the description adds no new semantics. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource: retrieving a cached directory overview for a relay from firehose.directory, and enumerates what it contains (PDS counts, account totals). It is distinguishable from the sibling get_pds_directory_info because the resource is a relay, though it never explicitly names that sibling to disambiguate.

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

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

There is no when-to-use guidance: no condition for picking this over get_pds_directory_info or count_records, and no stated prerequisites. The only context offered is the caveat 'Best-effort/cached data', which describes data quality rather than usage.

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 the safety profile (readOnlyHint, openWorldHint), so the bar is lower, and the description adds real value by enumerating the possible status outcomes and the accepted identifier forms. It doesn't discuss error behavior or what an empty/inactive result looks like, but the state enumeration is meaningful added 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?

Two tight sentences: the first front-loads what is returned, the second handles routing and the input. No filler or repetition.

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

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

An output schema exists, so return-value detail isn't needed, and the description supplies the routing rationale and status vocabulary an agent needs. Nothing essential is missing for a one-parameter read tool.

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

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

Schema coverage is 100% and the single 'repo' parameter is already documented as 'a handle or DID'. The description merely restates that an identifier is required, adding no syntax or format detail beyond the schema. Baseline 3 for fully schema-covered params.

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 resource (an account's repository status) and enumerates the distinct states returned (active, revision, takedown/suspended/deactivated/deleted). It explicitly distinguishes itself from get_profile, so an agent can pick it without inspecting 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 a concrete triggering question ('has @alice been taken down?') and names the sibling that cannot answer it (get_profile), which is strong routing guidance. It stops short of stating when NOT to use it (e.g., for normal profile data), so a full 5 isn't warranted.

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/openWorldHint, and the description goes well beyond them: it discloses breadth-first walk order, per-node depth and parent tagging, a cost cap, and truncation behavior. It also flags a real limitation — the descendant tree assumes the app.bsky.feed.post lexicon and will be empty for record types modeling replies differently. That is strong disclosure, though it leaves pagination/cap values unquantified.

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 behavior before caveats and alternatives; every sentence carries information. It is dense and slightly run-on (comma-spliced clauses around 'replies, replies-to-replies'), which costs a point on readability.

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 exists, return shape needn't be explained, yet the description still conveys the node structure (depth, parent) an agent must reason about. Behavior, lexicon caveat, and truncation escape hatch are all present; nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100% and there is a single parameter, so the schema already documents the URI format. The description's 'Input is a post's at:// URI' restates rather than extends the schema, so baseline 3 applies.

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

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

States a specific verb (reconstruct) and resource (the conversation around a post), then precisely scopes it: ancestor chain to root plus a bounded descendant reply tree. An agent can distinguish it from get_backlinks or list_backlink_records without opening a schema.

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

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

Explicitly names the user question it answers ('show me this whole conversation / what is this replying to?') and routes to a specific alternative (list_backlink_records on a post URI) when the tree is truncated. Both the use case and the escalation path are covered.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: results are newest-first, scope is limited to ONE category, and handles are verified via identity resolution rather than search. It does not address failure modes or rate limits, so it stops short of a 5.

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

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

Front-loaded with what the tool returns, followed by the workflow, the content-reading alternative, and the handle-resolution note. Four dense sentences, each carrying distinct information with no filler or repetition.

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

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

An output schema exists, so return values needn't be documented exhaustively, yet the description still previews the record shape. Combined with complete param coverage and the get_backlinks prerequisite workflow, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by defining the relational semantics of the two required params: `source` must be a category obtained from get_backlinks, and `target` is the same target passed to get_backlinks. That linkage meaningfully exceeds what the schema text conveys.

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

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

States a specific verb (List) and resource (backlink records), names what each record contains (author DID + verified handle + at:// URI, newest first), and characterizes the category scope with examples (liked, reposted, quoted, replied, mentioned, follows). It clearly distinguishes itself from get_backlinks (categories) and get_record (content), so an agent can route without opening either schema.

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

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

Gives an explicit ordered workflow: call get_backlinks first to obtain the category `source`, then pass it here. Also names the alternative and its trigger condition ('to read WHAT a referencing record says ... call get_record on its at:// URI'). Both when-to-use and when-to-use-something-else are spelled out.

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

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

Annotations already cover the safety profile (readOnlyHint, openWorldHint), so the bar is lower. The description adds genuinely useful behavior beyond them: it discloses that return URLs are PDS-native rather than CDN-hosted, and that input accepts a handle or DID.

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 mostly earns its sentences, but contains redundancy ('PDS-native, works for any PDS,not a CDN' repeats the same point, and there's a missing space after the comma) and the CID-reference aside could be tighter.

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?

An output schema exists, so return values need not be explained, yet the description still restates them (CID + getBlob URL). Input requirements, purpose, and the alternative are all covered, leaving nothing an agent needs to call the tool correctly missing.

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

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

Schema description coverage is 100%, so the schema already documents repo, limit, and cursor with constraints. The description only echoes 'a handle or DID' for repo and adds no syntax or format detail beyond the structured fields; baseline 3 applies.

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

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

States a specific verb and resource ('List the blobs ... hosted in an account's repository'), names the underlying lexicon, and clarifies what a blob is (uploaded media/attachments). It also differentiates from the sibling get_blob_info by scope (account-wide listing vs. single-CID lookup).

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

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

Gives clear context ('Answers what media does this account host?') and points to the alternative ('use this (or get_blob_info) to turn a CID into a fetchable URL'). However, it never states when to prefer get_blob_info over this tool, treating the two as freely interchangeable rather than giving a selecting condition.

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 the read-only (readOnlyHint) and open-world (openWorldHint) profiles. The description adds useful context beyond that: the tool returns resolved handles and endpoints, and the relay aggregates third-party/regional labelers, which corroborates the open-world hint. It does not discuss pagination or ordering, but the schema handles paging.

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 primary action and return contents, then the workflow relationship. Two sentences that each earn their place. Minor typographical run-on ('relay,each') is the only flaw.

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?

An output schema exists so return values need not be spelled out, yet the description still names the key fields. Combined with explicit routing to query_labels and annotation-covered safety, an agent has everything needed to call this correctly; only paging behavior is left entirely to the schema.

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

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

Schema description coverage is 100%, so limit and cursor are already fully documented in the schema (including the cursor-chaining instruction). The description adds no parameter meaning beyond that, 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?

Specific verb+resource: 'List the labeler (moderation) services known to the labeler relay' and it enumerates the returned fields (DID, resolved handle, service endpoint). It explicitly distinguishes itself from the sibling query_labels, which is the main confusion risk in this namespace.

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

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

States the sequencing rule outright: this is 'the discovery step BEFORE query_labels, which needs a labeler DID/handle up front.' It also names the concrete instances an agent would want (moderation.bsky.app and third-party/regional labelers) and the hand-off ('pass one to query_labels').

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 openWorldHint=true, so the safety profile is covered. The description's only added behavioral note is 'with pagination,' and even that is largely restated by the limit/cursor schema fields. It does not explain ordering, whether results can be empty, or rate limits.

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

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

Two tight sentences with the purpose front-loaded and no filler. The second sentence mostly duplicates schema-level detail on repo and collection, which slightly dilutes the conciseness.

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 an output schema present, return values need not be explained, and annotations cover the safety profile. The remaining gap is routing guidance relative to sibling list/get/count tools, but for a straightforward paginated list this is close to 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 all four parameters (repo, collection, limit, cursor) are already documented in the schema. The description repeats the repo/collection semantics without adding format or edge-case detail, 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 (list) and resource (records in a collection for an account), plus a scope modifier (pagination). This is clearly distinguishable from singular get_record and count_records, but it never names or contrasts those siblings explicitly, so it stops 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?

The description tells the caller how to fill in parameters ('Provide the repo... and the collection NSID') but gives no guidance on when to use this versus get_record, list_backlink_records, or count_records, and states no prerequisites or exclusions. Usage is only implied by the purpose sentence.

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 and openWorldHint; the description adds substantial behavioral context beyond that — the default single-request DID-only fast path, the slower/smaller enrich path with its effective ~20 page cap, and the pagination contract. This is exactly the kind of tradeoff detail annotations cannot express.

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 lexicon, then flows into usage, defaults, and input format with little waste. Slightly dense with a few near-redundant asides (e.g. 'Works for any PDS'), but each sentence roughly 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 paginated listing tool with an output schema (which handles return-value description), the description covers purpose, default vs enrich behavior, pagination via cursor, and expected input format. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents pds, limit, cursor, and enrich including defaults and the enrich/limit interaction. The description largely restates that (DIDs-only default, enrich resolving handles) and adds only the 'best for counting' rationale, 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 ('List the accounts (repositories) hosted on a PDS'), names the underlying lexicon, and specifies what each result contains (DID and active/takedown status, paginated). An agent can distinguish it from siblings like list_repos_by_collection or list_records 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 clear usage framing ('who is hosted on this PDS?' / counting) and an explicit when-to-use for enrich ('pass enrich=true only when you need handles'). It does not, however, explicitly name or exclude sibling alternatives such as list_repos_by_collection or search_accounts, so it stops 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?

Annotations declare readOnlyHint/openWorldHint, and the description goes further: it discloses the anonymous relay-served path, that the default is the public Bluesky relay rather than the account's PDS, and the speed/size tradeoff between DIDs-only and enrich=true. It stops short of discussing error behavior or rate limits, so not a 5.

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

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

Front-loads the core purpose and example before caveats, and every clause carries operational meaning. It is dense and slightly run-on with stacked parentheticals, 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?

With an output schema present, return values need no explanation, and the description covers scope, transport (relay vs PDS), pagination intent, and enrichment tradeoffs. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so 3 is the baseline, but the description adds value beyond the schema by clarifying that the relay defaults to the public Bluesky relay (the schema only says 'default') and by re-framing the enrich/limit interaction. Clear marginal contribution.

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

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

States a specific verb+resource (list repos publishing a given collection) with concrete examples ('who has an app.bsky.feed.generator?'), and explicitly differentiates from count_repos_by_collection, search_lexicons, and resolve_lexicon. An agent can identify the right tool 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 says when to use it (enumerate publishers of a collection) and when not to (use count_repos_by_collection for just a total). Names the relay default and how to query another, plus the pairing tools, leaving little 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 cover read-only and open-world behavior, but the description adds meaningful non-schema context: the call is anonymous, service-agnostic, and resolves the labeler's endpoint from its DID document rather than a hardcoded aggregator. It does not discuss rate limits or error behaviors, so not a 5.

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

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

Purpose and example are front-loaded in the first sentence, with the subject/labeler semantics in the second. Dense but every clause earns its place; the method-name parenthetical is slightly redundant with the title field being null.

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 an output schema present, return values need no explanation, and the description covers purpose, subject/labeler input semantics, and pagination implication via the cursor mention. It leaves out any failure modes (unknown labeler DID, invalid at:// URI), which keeps it short of 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 coverage is 100%, so the descriptions of limit, cursor, labeler and subject are already in the schema. The prose largely restates those (subject as DID/handle vs at:// URI, labeler as handle/DID) and adds only a concrete example value for labeler, so it stays at the baseline.

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

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

States a specific verb and resource ('what moderation labels a labeler has applied to a subject') and immediately names the ATProto method, so the agent knows exactly what is retrieved. It is clearly distinguishable from sibling list_labelers, which enumerates labelers rather than querying labels they applied.

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 quoted example question ('has @alice or this post been labeled spam/nsfw/hidden by labeler X?') gives a concrete usage context, effectively telling the agent when this tool applies. It does not, however, name an alternative tool or state when not to use it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety and network profile is covered. The description adds useful context that it is PDS-agnostic and that the response shape varies with input specificity, but says nothing about auth requirements, error behavior, or rate limits. With annotations carrying the safety burden, this is adequate but not rich.

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

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

Four short sentences, front-loaded with the core verb and resource, then input forms, then output variability, then scope. Every sentence earns its place and no filler is present.

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?

Input forms, output variability, and PDS scope are covered, and an output schema plus full schema descriptions handle return values and pagination. The one missing piece is routing guidance against the many overlapping read siblings, which an agent choosing among 26 tools would find useful.

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

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

Schema description coverage is 100%, so both the uri forms and the limit/cursor/include semantics are already fully documented in the schema. The description restates the input forms and adds nothing about the optional enrichments or pagination beyond what the schema provides, so baseline 3 applies.

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

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

States a clear verb+resource ('Resolve any AT Protocol identifier to JSON') and enumerates the accepted input forms, so an agent knows exactly what it consumes and produces. It does not explicitly name siblings like get_record, get_profile, or get_did_document that overlap on at:// inputs, so sibling differentiation is left implicit.

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

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

The description implies usage by explaining that output depends on input specificity (profile vs collection page vs record), which tells an agent something about when the tool is appropriate. However, it never states when to prefer it over get_record, list_records, or verify_handle, and gives no exclusions or prerequisites.

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 openWorldHint=true, so the safety and network profile is covered. The description adds only that the output contains a description and definition, which the output schema already carries, so it contributes little behavioral context (no auth, rate-limit, or failure 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?

Three short sentences, front-loaded with the purpose, then input, then return shape. No filler or redundancy beyond the example restated from the schema.

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

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

For a single-param read-only lookup with an output schema, the description is nearly sufficient: purpose, input format, and return content are all covered without needing to explain return values. Only the absence of any routing guidance against search_lexicons keeps it from being fully complete.

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

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

Schema coverage is 100% and the single nsid parameter is fully documented in the schema, including the same app.bsky.feed.post example repeated in the description. Baseline 3 applies since the schema does the work and the description adds nothing new.

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 (resolve) and resource (lexicon schema / record type), clarifying that the NSID identifies a collection schema rather than a record. It is distinguishable from search_lexicons and get_record, though it never names those siblings explicitly.

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 only implied: the agent must infer it should call this when it has an NSID and wants to learn what the record type means. No when-to-use condition, prerequisites, or alternatives (e.g. search_lexicons) are stated.

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

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

Goes well beyond readOnlyHint/openWorldHint by disclosing the AppView index dependency, possible missing accounts, and the critical caveat that results are search candidates rather than verified handle-to-DID mappings. These are non-obvious behavioral traits that affect trust decisions.

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

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

Three sentences, front-loaded with the action and scope, followed by return semantics, then the crucial verification warning. Every clause earns its place; 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 exists, the description need not explain returns in detail, but it still clarifies candidate semantics and verification needs. Combined with annotations and schema, an agent has everything needed to call and correctly interpret 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 100%, so the schema already fully documents query, limit, and cursor. The description only restates that search is by handle or display name and is paginated, adding no syntax or format detail beyond the structured fields.

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

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

States a specific verb and resource ('Search for AT Protocol accounts by handle or display name'), names the underlying data source, and describes the return shape and core use case. It clearly distinguishes this discovery tool from sibling verification/resolution tools.

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

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

Explicitly tells the agent when to use this tool and, more importantly, when not to trust its output: 'call verify_handle before trusting that a handle really belongs to a DID', and explains why resolve/get_profile are insufficient for authenticity. This is direct routing guidance against specific siblings.

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 as read-only and open-world, but the description adds crucial behavioral context: exact semantics of total vs matched, pagination via offset and limit, typeCounts returning a breakdown of matches, and otherTypes reporting excluded kinds. This is far beyond what annotations provide.

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

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

The description is dense but well-structured, with each sentence adding concrete information. It is longer than average but avoids fluff, front-loading the core purpose and then elaborating on behavior, which is appropriate for a search tool with nuanced semantics.

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

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

Given the complexity of the registry (multiple schema kinds, non-obvious type relationships, pagination), the description covers all necessary context for correct invocation: how to interpret total and matched, how to handle types, pagination, and when to use the sibling resolve_lexicon. An output schema exists, but the description still adds useful semantic detail about response fields.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description adds value by explaining that type does not imply query, showing examples like space.saebyeok.permissionSet, and clarifying substring matches and dot-prefix suffix matching for query. However, the schema already covers most of this, so a baseline 3 is appropriate.

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

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

States a specific verb+resource: 'Browse or search the registry of published AT Protocol lexicon schemas.' This clearly distinguishes it from sibling resolve_lexicon, which the description itself names as the alternative for a specific 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 says to use resolve_lexicon for a specific schema's full definition, and gives conditions for each mode: with query, type filter, or neither. It even handles the edge case of type-only searches and misspelled types.

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?

Beyond the readOnlyHint/openWorldHint annotations, it discloses that verification happens through two independent external mechanisms (DNS TXT and HTTPS well-known) and that per-method pass/fail is reported. This tells the agent it makes outbound network lookups and returns granular results, which the annotations alone do not convey.

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

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

The core operation is front-loaded in the first sentence, which is efficient. The trailing clause 'this gives cryptographic binding' is mildly redundant with 'Bidirectionally verify' and the run-on comma splicing slightly muddies the ending.

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 an output schema present, the description need not detail return values, and it still usefully notes that per-method results are returned. For a single-parameter, low-complexity verification tool it covers purpose, mechanism, and routing to alternatives adequately.

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

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

There is a single required 'handle' parameter with 100% schema description coverage, including an example (alice.bsky.social). The description adds no format or syntax guidance beyond the schema, so the baseline of 3 applies.

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

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

It names a specific verb (verify) and resource (handle ownership by DID) and specifies the two mechanisms used: DNS TXT and HTTPS well-known. This is clearly distinct from siblings like resolve or search_accounts, which the description itself characterizes as producing mere candidates.

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 a purpose-driven use case (checking for impersonation/spoofing) and contrasts itself with resolve/search results, which only 'give candidates' while this 'gives cryptographic binding.' The phrasing is slightly garbled and no explicit when-not-to-use case is given, so it falls short of 5.

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