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

With no annotations provided, the description carries the full burden. It discloses the return content (README, file listing, source files) but does not explicitly state safety (read-only), permissions, or error behavior. It implies retrieval but lacks explicit behavioral notes.

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 concise and well-structured: two sentences plus a focused Args section. The purpose is front-loaded, and every sentence earns its place, with no redundancy.

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

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

For a simple one-parameter retrieval tool, the description covers purpose, usage, parameter semantics, and return content. It lacks explicit note on side effects or error handling, but the output schema covers return structure. Given no annotations, a slightly more detailed behavioral note would push it to 5, but it is complete enough.

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

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

The input schema provides no description for the 'name' parameter (0% coverage). The description compensates with an Args section that explains the parameter, gives concrete examples, and references list_cookbook_examples to discover valid values. This adds significant meaning beyond the schema.

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

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

The description clearly states it retrieves a specific AT Protocol cookbook example by project name. This is a specific verb+resource combination and distinguishes itself from sibling tools like list_cookbook_examples, which lists all examples.

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 explicitly says 'Use this when you need implementation examples or starter code' and directs users to list_cookbook_examples for discovering available projects. This provides clear guidance on when to use this tool and an alternative.

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

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

Annotations are absent, so the description must disclose behavioral traits. It does so by stating the return content: 'Returns the full lexicon schema including type definitions, properties, descriptions, and cross-references.' This conveys what the agent can expect. It does not cover error handling or authentication, but for a simple read operation the transparency is adequate.

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 concise and well-structured: a one-sentence purpose, a sentence describing the return value, a usage statement, and a parameter definition. Every sentence provides unique value with no redundancy or filler. The front-loaded verb and resource make it easy to scan.

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

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

For a tool with only one parameter, no annotations, and an existing output schema, the description covers all necessary aspects: what it does, when to use it, what it returns, and what the parameter means. It is complete enough for an agent to select and invoke the tool correctly without further clarification.

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

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

Schema coverage is 0% since the input schema only lists 'nsid' with no description. The description compensates fully with an Args section that defines 'nsid' as 'The Namespaced Identifier' and provides three concrete examples ('app.bsky.feed.post', 'com.atproto.repo.createRecord', 'chat.bsky.convo.sendMessage'). This gives the agent exactly what it needs to understand the parameter.

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

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

The description opens with a clear verb and resource: 'Retrieve a specific AT Protocol lexicon by its NSID.' This directly specifies what the tool does and distinguishes it from sibling tools like list_lexicons and search_lexicons by emphasizing lookup of a specific NSID rather than listing or searching. The additional clause 'complete definition of a specific endpoint or record type' reinforces the unique purpose.

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 provides explicit guidance with 'Use this when you need the complete definition of a specific endpoint or record type.' This tells the agent when to choose this tool. However, it does not explicitly mention sibling alternatives or state when not to use it, which would have made the guidance even stronger.

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

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

With no annotations, the description carries the full burden. It discloses that it lists all examples, the optional language filter, and the empty-default behavior. It does not detail output format or potential pagination, but an output schema exists to cover return structure.

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?

Concise, front-loaded with the purpose, then a short usage line, then parametrized arg documentation. Every sentence contributes meaning without redundancy.

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

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

For a simple one-parameter list tool, the description covers purpose, usage, parameter semantics, and sibling differentiation. An output schema exists, so return format is covered elsewhere. No critical information 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 schema only has 'language' with a default. The description enriches this by listing valid values ('python', 'go', 'typescript', 'javascript') and explaining that empty means 'list all.' This fully compensates for 0% schema description coverage.

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

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

Description states 'List all AT Protocol cookbook examples (starter projects and scripts)' with a specific verb and resource. It clearly distinguishes from get_cookbook_example by mentioning listing vs fetching specific examples.

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 instructs 'Use this to discover available example projects before fetching specific ones with get_cookbook_example,' naming the alternative. Also specifies how to use the language filter and the default behavior.

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

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

No annotations are provided, so the description must carry the full burden. It discloses the filtering behavior with examples and the 'Leave empty to list all' behavior, but does not mention pagination, rate limits, or whether the operation is guaranteed read-only (though 'List' implies it). It adds some context beyond the schema, but could be more explicit about response size or limitations.

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 concise and well-structured: a one-sentence purpose, a usage note, and a compact Args block with examples. It front-loads the main action and avoids unnecessary detail. Every sentence contributes value.

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

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

For a simple list tool with one optional parameter and an output schema, the description is complete enough. It explains what it does, when to use it, and the parameter semantics. It does not describe return values, but the output schema covers that. It lacks caveats like pagination or auth, but given the tool's simplicity and the presence of an output schema, the description suffices.

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 schema provides only a 'namespace' string with default '', with no description. The description's Args section fully explains the parameter: it is an optional namespace prefix, provides concrete examples ('app.bsky.feed', 'com.atproto.repo', etc.), and clarifies that leaving it empty lists all. This adds significant meaning beyond the schema, compensating for the 0% schema description coverage.

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

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

The description opens with 'List all AT Protocol lexicons, optionally filtered by namespace prefix,' which clearly identifies the verb (list), resource (AT Protocol lexicons), and scope (optional namespace filter). It also distinguishes itself from the sibling tool get_lexicon by stating this is for discovering lexicons before fetching specific ones. This gives a precise purpose.

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 explicitly states 'Use this to discover available lexicons and their NSIDs before fetching specific ones with get_lexicon,' providing a clear when-to-use context and referencing the next step. It does not mention alternatives like search_lexicons or exclusion cases, but the guidance is sufficient for typical use.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the operation 'may take several minutes as it clones repositories and rebuilds the embeddings index,' which is important behavioral context for an agent deciding to invoke it. However, it doesn't detail side effects like cache invalidation or whether the index is temporarily unavailable during rebuild.

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, first is the action, second is usage and behavior. No fluff, front-loaded with the operation name and scope.

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

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

For a zero-parameter maintenance tool, the description covers what it does, when to use it, and how long it takes. The output schema handles return values, so this is sufficient for an agent to make an informed decision.

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

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

The input schema has zero parameters, so the baseline is 4. The description adds no parameter information because there are none; the schema already covers everything with 100% coverage.

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

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

The description opens with a specific verb+resource: 'Force re-fetch all AT Protocol source repositories and rebuild the search index.' This clearly distinguishes it from the sibling search/list/get tools, which are all read-only queries.

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

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

Explicitly states when to use: 'Use this when you suspect the documentation is outdated or when upstream repos have been updated.' This is clear context, though it does not list when-not-to-use or name alternative tools, so it earns a 4 rather than a 5.

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

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

With no annotations provided, the description carries the full burden. It discloses 'Search is hybrid (keyword + semantic), so exact identifiers like NSIDs ... match reliably', which is a useful behavioral trait beyond the obvious read-only nature of searching. It does not mention auth requirements or rate limits but still adds meaningful context.

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

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

The description is moderately long but every sentence serves a purpose: purpose, usage, search behavior, and parameter details. The parameter explanations are structured clearly. It earns its length, though it could be slightly tightened without losing value.

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

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

Given the tool's moderate complexity (4 parameters, output schema exists), the description covers the essential contexts: what it searches, when to use it, how the search behaves, and what each parameter does. It does not repeat return values (already in output schema) and is complete for a search tool, though it could mention default source coverage or result ordering.

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

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

The input schema has 0% description coverage, so the description must compensate. It comprehensively explains every parameter, including the exact allowed values for source ('atproto-website', 'bsky-docs', 'lexicons', 'cookbook'), content_type ('guide', 'spec', 'blog', 'reference', 'example'), and the range/default for limit ('1-20, default 10'). This is exceptional added value.

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

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

The description opens with 'Search across all AT Protocol documentation, lexicons, Bluesky API docs, and cookbook examples', which uses a specific verb ('search') and resource scope ('all AT Protocol documentation') that clearly distinguishes it from sibling tools like search_lexicons and search_bsky_api by its comprehensive coverage.

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

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

The description states 'Use this tool to find information about AT Protocol concepts, endpoints, data structures, authentication, federation, and implementation patterns', giving clear guidance on when to use it. However, it does not explicitly mention when NOT to use it or name alternative tools, so it stops short of a perfect 5.

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

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

No annotations are provided, so the description carries the burden. It indicates a search operation (implying read-only) and specifies the content scope, but does not disclose potential rate limits, authentication requirements, or result behavior. For a search tool with no side effects, 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?

The description is concise and front-loaded with the purpose. The args section is clearly formatted and the examples are useful. It could be slightly more structured (e.g., bullet points) but remains readable and focused.

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

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

For a simple 2-parameter search tool with an output schema, the description covers the essential usage and parameter details. It lacks explicit references to sibling tools or limitations, but is otherwise complete for its complexity level.

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?

With 0% schema description coverage, the description fully compensates by explaining both parameters: query includes multiple examples, and limit specifies a valid range (1-20) and default (10). This adds significant meaning beyond the bare schema.

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

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

The description clearly states the tool searches Bluesky developer API documentation, specifying the resource (docs.bsky.app) and scope (guides, tutorials, advanced topics). It distinguishes itself from siblings by focusing on Bluesky-specific features, but does not explicitly name alternative tools like search_atproto_docs.

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

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

It explicitly states 'Use this for questions about Bluesky-specific features like the firehose, federation, moderation, or API usage patterns', giving clear contextual guidance. However, it does not provide when-not-to-use instructions or mention alternative tools for other types of queries.

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

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

No annotations are provided, so the description must fully disclose behavioral traits. It mentions 'semantic search' and search scope, but does not state whether the operation is read-only, any rate limits, return format, pagination behavior, or other side effects. This is a significant gap for a tool with no annotation support.

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

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

The description is compact and well-structured: a one-sentence core action, a supplementary scope sentence, and a clear Args list. It is front-loaded, contains no fluff, and every sentence adds value.

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

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

For a simple search tool with an output schema and only two parameters, the description covers the essential purpose and usage. It explicitly differentiates from one sibling and provides parameter context. However, it lacks a brief note on what output format to expect (though output schema exists) and does not position itself relative to all relevant siblings, leaving minor completeness gaps.

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?

With 0% schema coverage, the description compensates well by explaining each parameter: query is described with illustrative examples and limit includes a range (1-20) and default (10). This adds meaning beyond the schema's bare types and defaults, though it could be slightly more detailed about the query's semantic matching behavior.

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

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

The description clearly states the tool's action ('Search within AT Protocol lexicons using semantic search') and its scoped resource ('lexicon descriptions, property names, types, and definitions'). It also explicitly distinguishes itself from a sibling tool ('More targeted than search_atproto_docs when you specifically need lexicon/schema information'), making its purpose unmistakable.

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 provides explicit usage guidance: 'More targeted than search_atproto_docs when you specifically need lexicon/schema information.' This names an alternative and states the condition under which this tool is preferred. However, it does not compare against all siblings (e.g., search_bsky_api), leaving some ambiguity for broader choices.

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