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

With no annotations, the description carries the behavioral disclosure burden. It clearly states that the tool returns structured data and lists the categories, which is useful. It does not explicitly say the operation is read-only, how the code graph is accessed, or describe failure behavior, though nothing suggests side effects.

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

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

The description is compact and well-structured: a one-line purpose statement, a concise list of return categories, and a clearly labeled Args section. Every sentence adds value and there is no redundant 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?

Since there is no output schema, the description compensates by enumerating the major return categories and giving an example for the single parameter. It is complete enough for correct invocation, but the absence of explicit read-only confirmation and sibling differentiation leaves a small gap.

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

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

Schema coverage is 0%, so the description must compensate. It does by defining the only parameter: 'project: Project name (e.g. "my-app", "backend-api")', which provides both meaning and examples. For a single required string parameter, this is sufficient, though it could mention whether an ID, path, or exact name format is expected.

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

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

The description states a clear purpose: it provides an architecture overview of a project from the code graph, and it enumerates concrete return categories such as stack, languages, directory layers, key patterns, top dependencies, and hub files. It does not explicitly differentiate itself from sibling tools like codegraph_repomap or codegraph_stats, but the purpose is not vague.

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 intended use case is implied by 'Architecture overview' and the listed output categories, suggesting the tool is for high-level project understanding. However, there is no explicit when-to-use guidance, no exclusions, and no mention of alternatives among the many sibling tools.

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 explains the tool's data model and provides example queries, which sets expectations about the graph structure. However, it does not disclose whether queries are read-only, performance implications, potential for heavy load, or error behavior on malformed queries. For a raw-query tool, this is a notable gap.

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

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

The description is well-structured: a single sentence opens with the core function, then a structured list of graph components, followed by examples. It is slightly long but each element earns its place, especially the examples which are essential for an action with a single free-form parameter. Dense but not bloated.

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

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

The description covers the graph schema, edge types, and parameter semantics, and there is an output schema present (not shown) that may convey return structure. What is missing is guidance on performance, query limits, or security considerations. For a power-user tool, this is adequate but not fully comprehensive.

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 defines 'query' as a string with 0% description coverage. The description compensates fully by specifying that it is a Cypher query string, describing the available entities and edges, and offering multiple concrete examples that illustrate valid query syntax. 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 executes a raw Cypher query against a code intelligence graph, specifying node types and edge types. This provides a precise verb and resource, and visually distinguishes it from siblings like source_search or kb_search, which are likely semantic. The examples solidify the intended scope.

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 conveys that this is for raw Cypher queries, which implies flexibility for complex or custom analyses. However, it does not explicitly state when to prefer this over sibling tools like codegraph_stats or source_search, nor does it mention any exclusions or recommended fallbacks. The usage context is clear but not contrastive.

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 carries the full burden. The description explains the tool generates a YAML map, which implies a read-only operation, but it does not explicitly state that it is non-destructive, requires no special permissions, or has any side effects. No contradictions exist, but the description would benefit from an explicit statement that it only reads repository data.

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

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

The description is well-structured with a concise intro and a clean 'Args:' section. Every sentence is purposeful, with no unnecessary verbosity. It is front-loaded with the core purpose and uses a list for parameters, making it easy to scan. A minor improvement would be to mention the output format once at the start, which it already does.

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 tool with two parameters and no output schema, the description is fairly complete. It explains the purpose, output format, and both parameters. It does not explicitly cover error conditions or prerequisites (e.g., the project must be indexed), but these are not critical for basic usage and are likely implied by the context of the codegraph system.

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 has 0% description coverage, so the description must compensate. It does so by explaining each parameter: 'project: Project name (e.g. "my-app")' and 'limit: Maximum number of top files to include (default 20)'. It adds examples and semantic meaning, although it leaves some ambiguity about 'most important' and how the limit is applied.

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 purpose: 'Generate a YAML-formatted repository map showing the most important files and their symbols.' It specifies the verb 'Generate', the resource 'repository map', and the output format (YAML). This distinguishes it from siblings like codegraph_query and codegraph_explain, which focus on querying or explaining code.

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 usage context: 'Helps understand the global structure of a project without reading all files.' This gives a clear scenario for when to use the tool. However, it does not explicitly mention when NOT to use it or contrast with alternative tools, which is a minor gap.

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 key behavioral traits: returns a list, includes dependent projects, and sorts by number of projects (most shared first). It does not describe side effects, but the nature ('Returns') implies a read-only query. Minor gaps like pagination or error handling are not critical for a zero-parameter tool.

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

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

The description is concise and front-loaded: it opens with the core purpose ('Packages shared...') and then explains the output and sorting. Every sentence adds value, and there is no filler. It is appropriately sized for a simple tool.

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 simplicity (no parameters, no annotations) and the presence of an output schema, the description covers the essential information: what it returns, the ordering, and a use case. It does not explain what constitutes a 'package' or a 'project,' but these are likely defined elsewhere in the code graph context. Overall, it is sufficiently complete for an agent to call it 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?

There are zero parameters, so the schema coverage is 100% by default. The baseline for zero parameters is 4, and the description offers no parameter details because none exist. This score reflects that there is nothing to explain and the description is not lacking in this area.

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 specific resource ('packages shared across multiple projects') and the action ('Returns list...'). It is distinct from siblings like codegraph_stats or codegraph_query by focusing on shared dependencies across projects. The wording is unambiguous and directly conveys what the tool does.

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 context for when to use the tool: 'Useful for finding common dependencies and potential shared infrastructure.' This gives clear use-case guidance. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of the highest score for explicit exclusions.

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

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

There are no annotations, so the description carries the full burden. It discloses that the tool returns statistics and counts, which implicitly indicates a read-only aggregation, but it does not explicitly state the absence of side effects, potential resource costs, or any error behavior. For a simple stats tool, 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?

Two compact sentences: the first front-loads the core purpose, the second enumerates the returned metrics. Every word earns its place; no fluff 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?

For a no-argument statistics tool with no output schema, the description is complete: it lists the exact categories of counts returned. An agent can predict the shape and intent of the call without needing extra context.

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

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

The tool takes zero parameters, so schema coverage is trivially 100%. Baseline for 0 parameters is 4; there is no parameter information needed beyond what is already empty.

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

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

The description names a specific verb ('Get') and a concrete resource ('code intelligence graph statistics'), then enumerates exactly what is returned (counts of projects, files, symbols, packages, sessions, edge type breakdown). This clearly distinguishes it from sibling tools like codegraph_query or codegraph_repomap, which target different purposes.

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 — if an agent needs aggregate counts or a breakdown of graph elements, this is the tool — but it does not explicitly state when to use it over alternatives or mention any exclusions. No sibling differentiation is provided in the text.

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 convey behavioral traits. It explains that the tool performs semantic search, supports two languages, and can expand results with graph neighbors, which is useful. However, it does not disclose any side effects, permissions, or safety considerations. Since it is a search tool, read-only behavior is implied, but the lack of explicit confirmation and no annotation coverage prevents a higher score. There is no contradiction with annotations, so this is not a 1.

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. It leads with the core purpose, then provides a brief behavior note, and finally lists arguments in a clear format. Every sentence adds value; the argument list is introduced with 'Args:' and each parameter has a short explanation. It is not overly verbose and avoids repetition, earning a 4.

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 are already specified. The description covers the main functionality and parameters, but lacks details on edge cases like maximum n_results, how to determine valid doc_type values, or the exact behavior of expand_graph beyond a one-hop expansion. These are not critical given the output schema, but the vagueness around doc_type and expand_graph leaves some gaps. A 3 is appropriate.

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 must compensate. It does provide explanations for all four parameters: query with examples, n_results with default, doc_type as a filter, and expand_graph as a boolean. However, doc_type is described vaguely ('depends on your KB schema') without concrete options, and n_results lacks range or constraints. The description adds meaning beyond the schema but does not fully cover all ambiguities, justifying a 3.

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

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

The description clearly identifies the tool as performing semantic search over the knowledge base, specifically targeting markdown documents with YAML frontmatter. It adds details about multilingual support (Russian and English), which helps distinguish it from a generic search. However, it does not explicitly name any sibling tools or contrast them, so it earns a 4 rather than 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 provides clear guidance on using parameters such as expand_graph to include knowledge graph neighbors and doc_type for filtering, which is helpful. It implies when the tool should be used (semantic search scenarios) but does not explicitly state when not to use it or mention alternatives like session_search or source_search. The exclusion guidance is absent, limiting the score to 3.

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 behavioral burden. It does disclose the backend ('sentence-transformers'), notes that it is memory-safe, and implies an index mutation. However, it does not state whether existing vectors are replaced or cleared, whether the operation is expensive or blocking, or what permissions are needed.

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 purpose, a clear when-to-use instruction, a useful safety/backend note, and a simple Args section. Every sentence earns its place, and key information 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?

For a one-parameter tool, this is mostly adequate, but significant gaps remain because there are no annotations and no output schema. The description does not mention return values, the cost or duration of reindexing, whether the operation overwrites the existing index, or how to handle partial failures. These are relevant for a mutating indexing 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?

The only parameter, 'project', is described as 'Project name or path' with concrete examples ('my-app', '~/projects/my-app'). With 0% schema description coverage, this fully compensates for the missing schema-level detail and adds real meaning beyond the parameter's title.

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

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

The description states a specific verb ('Reindex'), a specific resource ('a project's source code and docs'), and a clear target ('FalkorDB vectors'). It clearly differentiates this tool from sibling search/query tools by framing it as the index-updating operation.

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

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

The description gives a clear usage condition: 'Call this after significant code changes to update the search index.' It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to know when to select this tool.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly reveals a notable side effect: 'Auto-indexes the project on first search if no index exists.' It also describes the semantic search mechanism and per-project vector DBs. Missing details like rate limits or response behavior are less critical here, but the auto-indexing disclosure is valuable and non-obvious.

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

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

The description is well-structured and efficient: a one-sentence purpose, two clarifying sentences, then a clean Args block. Every sentence adds value, and the most important facts are front-loaded. No filler or redundant phrasing.

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 four-parameter search tool with an output schema, the description covers purpose, behavior, parameter semantics, and search scope. Auto-indexing behavior is disclosed, and the output schema handles return-value documentation. The only slight gap is lack of explicit sibling differentiation, but that does not make the description incomplete for invoking the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate fully—and it does. Every parameter is explained with examples (e.g., query examples, project paths, n_results default, chunk_type filter values). The inclusion of 'Omit to search all' for project adds crucial semantic meaning not inferable from the schema alone.

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, specific verb and resource: 'Semantic search over project source code and documentation.' It further specifies per-project FalkorDB vector DBs, which helps distinguish it from generic search. However, it does not explicitly contrast itself with sibling tools like source_search or kb_search, leaving some differentiation to inference.

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 clear use-case guidance: 'Useful for finding code patterns, functions, classes, and docs across projects.' This tells an agent when to invoke the tool. It does not name alternatives or state when not to use it, but the context is sufficient for most selection decisions.

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 shoulders the full burden of disclosing behavior. It does describe the two return modes (list vs. detail) and implies a read-only operation, but it does not explicitly confirm safety, mention error handling (e.g., what happens if the name does not exist), or note any side effects or authentication requirements. The description adds some behavioral detail but is not comprehensive for an unannotated tool.

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

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

The description is highly concise, front-loading the core purpose and then clearly delineating the two modes before listing the argument. Every sentence contributes value, with no filler. The structure is optimal for quick agent scanning.

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 (single optional parameter) and the presence of an output schema (which handles return value documentation), the description covers the essential calling context: what the tool does and how the parameter alters the result. It could go further by noting expected error behavior or clarifying what 'active projects' means, but overall it is sufficient 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?

The input schema only defines an optional 'name' field with a default null and anyOf string/null, providing no semantic meaning. The description compensates by explaining that omitting the name returns a list of all projects, while including it returns detailed info for one named project. This adds significant behavioral meaning beyond the raw schema, effectively covering the parameter's semantics despite 0% schema 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 clearly states the tool retrieves project information from a registry, with two explicit modes: listing all active projects (with stacks) when no name is given, and returning detailed info for a specific project when a name is provided. This is a specific verb-resource pairing. However, it does not differentiate itself from sibling tools like source_list or project_code_search, which could overlap in purpose or context.

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 when to omit the name (to get a full list) versus when to provide it (to get a single project's details), which is clear self-usage guidance. However, it does not explicitly tell the agent when to choose this tool over siblings, nor does it mention any exclusion criteria or alternatives. The guidance is contextually clear but lacks cross-tool comparison.

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

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

With no annotations, the description carries the burden of explaining behavior. It conveys that this is a semantic, non-exact search over session history, which is useful, but it does not disclose return format, result ordering, or any access or side-effect implications. This is adequate but not richly transparent.

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

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

The description is front-loaded with the core purpose and immediately gives practical usage examples, followed by a compact parameter list. The second sentence is somewhat redundant with the first, but overall it is efficient and scannable.

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 three-parameter search tool with an output schema, the description covers what the tool does, when to use it, and what each parameter means. It does not over-explain return values, which is acceptable given the output schema is present. It is complete enough for an agent to call it 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 0%, so the description's Args section is the primary documentation. It explains all three parameters with examples and defaults, covering query, n_results, and project. Minor details like n_results bounds or project filtering semantics are not specified, but the description compensates well.

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

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

The description names a specific verb ('search') and a specific resource ('Claude Code chat session history'), and clarifies that it finds past sessions by topic or content. This clearly differentiates it from sibling code-search and codegraph 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?

The examples ('how did I solve X?', 'when did I work on Y?') give clear situations where this tool is appropriate. It does not explicitly state when not to use it or name alternatives, but the intended use cases are obvious enough.

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

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

With no annotations provided, the description carries the disclosure burden. It adds useful behavioral context beyond the title: the storage location (~/.solo/sources/), that sizes are shown, and that YouTube sources include a videos/video_chunks breakdown. The verb 'List' strongly implies a read-only operation, though it does not explicitly state side-effect safety.

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 three short sentences with no filler. The opening sentence gives the primary purpose, and the following sentences add specific and relevant details about location, sizes, and YouTube-specific fields. It is front-loaded and every sentence earns its place.

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

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

For a no-argument list tool with an output schema present, the description is complete: it states what is listed, where the data comes from, what measurements are included, and the special case for YouTube sources. No additional context appears necessary for an agent to select and invoke the tool correctly.

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

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

The input schema has zero parameters and schema coverage is 100%, so there is no parameter documentation burden. The 0-parameter baseline of 4 applies; the description adds no parameter meaning because none is needed.

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

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

The description states a specific verb ('List') and resource ('indexed external sources') and adds a document-count detail. It further clarifies scope by specifying all source graphs under ~/.solo/sources/, which distinguishes it from sibling tools like source_search, source_tags, and source_related as a global enumeration rather than a filtered query.

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 use when an overview of all indexed sources and their sizes/document counts is needed, but it does not explicitly say when not to use it or name alternatives. There is no explicit routing guidance against sibling tools, so the agent must infer the usage boundary from the word 'List' and the scope detail.

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 bears the full responsibility for behavioral disclosure. It explains the operation (finding related videos) and the ordering (by number of shared tags), which is transparent about the result behavior. However, it does not explicitly state that the operation is read-only, any authentication requirements, rate limits, or potential side effects. Since 'find' implies a non-mutating query, this is largely implicit, but the description could be more explicit.

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 succinct and well-structured: a one-sentence purpose followed by a brief explanation and an argument list. Every sentence adds value, and the most important detail (the purpose) is front-loaded. It avoids fluff and is appropriately sized for the tool's simplicity.

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

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

The tool has an output schema, so return values are likely documented there, and the description still notes the sorting order, which is helpful. However, it does not mention what happens when no related videos are found, nor does it specify the expected source format beyond the default. Given the relatively simple scope, the description is adequate but leaves some expected details unaddressed, such as error behavior or valid source names.

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

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

The input schema provides only types and a default for source; it has no descriptions (coverage 0%). The description compensates by defining video_url as 'YouTube video URL or video ID' and noting source defaults to 'youtube.' This adds meaning beyond the schema, though it does not enumerate possible source values. Given the schema's absence of guidance, this is a solid 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?

The description opens with a precise statement: 'Find related videos by shared tags.' It clearly identifies the verb (find), the resource (related videos), and the mechanism (shared tags), and then adds sorting criteria. This sets it apart from sibling tools like source_list or source_search, which likely handle listing or searching sources, so an agent can readily distinguish it.

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 no guidance on when to prefer this tool over alternatives, nor any exclusions or prerequisites. It does not mention sibling tools or suggest alternative actions for different scenarios. An agent is left to infer that this is for retrieving related content based on video tags, but no explicit when-to-use or when-not-to-use guidance is given.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It reveals important operational traits: each source is stored in its own FalkorDB graph, YouTube videos are chunked by chapters with chapter name and timecode in results, and cross-source search merges by relevance. This is meaningful context beyond the schema, though it does not cover pagination, return format details, or potential side effects.

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

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

The description is well-structured with a front-loaded purpose statement, a concise behavioral note, and a clear Args section. Every sentence adds useful information; there is no fluff or redundancy.

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

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

The description is complete for a search tool: it covers behavior, merging, YouTube chunking, and parameters. The output schema exists, so return values are likely already described elsewhere. Minor missing context includes how to obtain the full list of available source names, though a sibling tool source_list exists for that purpose.

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

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

Schema description coverage is 0%, so the description must explain the parameters—and it does. Query examples are given, the source filter is explained with examples and the instruction to omit it to search all, and n_results default is stated. This fully compensates for the schema's lack of descriptions.

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

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

The description states a clear action and resource: 'Search indexed external sources (Telegram, YouTube, etc.)'. This is specific enough to communicate the tool's core function. However, it does not explicitly differentiate itself from sibling tools like kb_search or web_fetch, relying on the reader to infer the scope of 'external sources'.

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 clear guidance on the source filter behavior: 'Without source filter, searches all sources and merges by relevance.' This tells the agent when to omit the source param and what happens in that case. It does not explicitly instruct when to use this tool over alternatives like kb_search or web_fetch, but the context is strong enough to imply 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?

With no annotations, the description must carry behavioral disclosure. It adds useful context: tags are assigned automatically via zero-shot embedding similarity during video indexing, and are shared across videos. However, it does not clarify whether the operation is strictly read-only, how counts are computed, or any caveats such as staleness or re-indexing effects.

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

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

The description is compact and front-loaded with the main purpose, followed by relevant mechanism context and a parameter note. Every sentence adds value and there is no redundancy or fluff.

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

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

The tool is simple, and the output schema presumably covers return values. Yet the description leaves a notable gap: it does not tell the agent how to obtain valid source names or that source_list might need to be called first, and it omits any mention of pagination or limits. Overall it is adequate but not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate for the undocumented 'source' parameter. It merely restates 'Source name (default: "youtube")', which adds little beyond the schema's title and default. It does not provide valid source examples, format constraints, or how source affects the returned tags.

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

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

The description clearly states a specific action and resource: 'List all auto-detected topics with video counts.' It is unambiguous and distinct from siblings like source_list or source_search, but does not explicitly name or differentiate itself from them, so it falls 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 implies usage through context: tags are auto-detected, shared across videos, and enable topic clustering. However, there is no explicit guidance on when to choose source_tags over sibling tools or any exclusions, leaving the agent to infer the appropriate context.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals automatic handling of redirects, cookies, and anti-bot headers, and explains the dual output modes (plain text vs raw HTML). It stops short of describing failure modes or JavaScript-rendering limitations, but the core runtime behaviors are transparent.

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

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

The description is compact and well organized: one sentence for the core purpose and behavior, another for return types, then a minimal Args list. Every sentence contributes meaningful information with no fluff 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?

For a simple fetch tool with four parameters and no output schema, the description covers the essential aspects: what it fetches, how it behaves, return types, and all parameters with defaults. It doesn't mention error handling or non-HTML responses, but those are minor omissions given the straightforward use case and sibling context.

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 Args section adds meaningful semantics to every parameter: url, max_length (in chars), extract_text (strip HTML), and timeout (in seconds) with defaults. This fully compensates for the 0% schema description coverage, giving the agent a complete understanding beyond bare parameter names.

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 begins with a specific verb and resource — 'Fetch a URL' — and immediately adds distinctive behavior ('with browser-like headers to bypass basic bot protection'). It clearly distinguishes this tool from the source-code-oriented sibling tools by domain and use case.

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 clearly implies when to use the tool: when needing to retrieve web content, especially when basic bot protection may interfere. It doesn't explicitly mention when not to use it or name alternative tools, but among the listed siblings there is no competing fetch tool, so the intended context is clear.

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