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 indicates mutation ('Add') and mentions a return value, but does not disclose idempotency, uniqueness constraints, or error scenarios. This leaves significant ambiguity for an 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 concise with a single introductory sentence followed by a clear list of parameters. Every sentence serves a purpose, and the structure is easy 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?

For a simple tool with no output schema and no annotations, the description covers the basic functionality and parameters. However, it omits the default value for 'type' (concept) and does not elaborate on the return structure beyond 'entity details'. It 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 description includes an Args section that explains the purpose and acceptable values for each parameter, providing examples for 'name' and clarifying 'type' and 'metadata' meaning. This adds value beyond the schema which only has titles and defaults. With 0% schema description coverage, 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 clearly states the tool adds an entity to the knowledge graph, specifying the verb 'Add' and the resource 'entity to the knowledge graph'. It is distinct from sibling tools like add_relation and add_tag.

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 does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusion criteria. It is minimally adequate but lacks contextual direction.

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 provided, so description carries burden. It discloses creation of a directed relation but does not mention side effects, destructive behavior, authorization needs, or constraints. Limited transparency.

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 short, front-loaded with the action, and includes a structured list of arguments and return. Every sentence is relevant, no 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?

For a simple mutation tool with 4 parameters and no output schema, the description covers operation, parameters, and return. Lacks error conditions or constraints, but overall adequate.

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 description compensates by explaining each parameter: source_id, target_id, rel_type with examples (CALLS, DEPENDS_ON, CONTAINS), and weight with range (0.0 to 1.0). Adds significant meaning beyond schema, though could be more precise about valid rel_type values.

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 explicitly states 'Add a directed relation between two entities,' providing a specific verb and resource. It distinguishes from sibling tools like add_entity and add_tag.

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?

No guidance on when to use this tool versus alternatives, no prerequisites or exclusions mentioned. The description only explains parameters without 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?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states that the tool creates a tag but does not mention side effects, permissions, uniqueness constraints, or return 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?

The description is a single sentence with no extraneous information. 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 creates a resource and has siblings, the description is incomplete. It does not explain what the tool returns after creation, whether tags must be unique, or how this relates to other tagging operations.

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 description coverage, and the tool description adds no additional meaning to the parameters. For example, the 'name' parameter has no format or uniqueness hints, and 'color' and 'description' lack allowed values or constraints.

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 verb and resource ('Create a new tag') and the purpose ('for categorizing documents'). However, it does not differentiate from the sibling tool 'create_tag', which appears to have the same 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?

No guidance is given on when to use this tool versus alternatives like 'create_tag' or 'tag_document'. An agent would have no context to decide which tool to invoke.

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, and the description does not disclose behavioral traits such as read-only nature, authentication needs, or side effects. It only describes input and output.

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 short with an opening one-liner and structured Args/Returns sections. It is front-loaded and efficient, though could be slightly more concise.

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 2 parameters, no annotations, and an output schema (explaining returns in text), the description covers basic usage but lacks context on graph nature, prerequisites, or error cases, leaving 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?

Schema coverage is 0%, so the description adds meaning by explaining start_entity_id and max_depth (with range 1-10). However, it lacks details like entity type requirements or error handling, making it adequate but not comprehensive.

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 'BFS traversal from a starting entity,' which is a clear verb (traversal) and resource (entity graph). However, it does not distinguish from sibling tools like search_graph or get_entity_relations.

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?

No guidance is provided on when to use BFS vs alternatives, nor any when-not-to-use conditions. Given sibling tools like search_graph, context on graph traversal choice would be helpful.

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 fully disclose behavioral traits. It states 'Check out' but does not clarify if it modifies state, requires write permissions, or is reversible. No details on side effects or concurrency are provided.

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 very concise (one sentence, 10 words), which is efficient but sacrifices essential detail. It is front-loaded but insufficiently informative for a tool with multiple siblings.

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 complexity with many sibling tools and no output schema, the description fails to provide complete context. It does not explain the effect of checkout, return value, or how it relates to branches and versions.

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 description does not explain the 'version' parameter beyond schema. With 0% schema description coverage, it fails to add meaning such as how to obtain or interpret version numbers, leaving the agent without necessary 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?

The description clearly states the verb 'Check out' and resource 'table version' with a specific purpose 'for time-travel queries.' It differentiates from siblings like restore_version and list_versions by implying a query-only operation, though it could be more explicit.

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

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

The description provides a context (time-travel queries) but gives no explicit guidance on when to use versus alternatives like restore_version or list_versions. No when-not or prerequisite information is included.

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 provided, so description must cover behavioral traits. It only mentions optional version input but does not disclose naming constraints, permission requirements, side effects, or what happens upon creation.

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?

Single sentence, no fluff. However, the brevity sacrifices essential detail for an agent.

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 2-parameter creation tool without output schema or annotations, the description is insufficient. It does not explain return value, error conditions, or what 'branch' means in this 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?

Schema coverage is 0% and description only hints at 'from_version' being optional, leaving 'branch_name' completely unexplained. No constraints, format, or examples provided.

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 clearly states the action (create branch) and the optional version parameter. It is specific and distinguishes from listing or switching branches, but does not explicitly differentiate from siblings like 'checkout_version'.

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?

No guidance on when to use this tool vs alternatives. With many sibling tools (list_branches, switch_branch, checkout_version), the agent lacks context for selection.

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 full burden for behavioral disclosure. It mentions inputs and a vague return, but omits critical details like whether tags are unique, if re-tagging overwrites, or any 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 short (4 lines) and well-structured with a purpose statement, parameter list, and return note. Every sentence adds value 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 two-parameter creation tool, the description covers the basics. However, it lacks detail on expected behavior (e.g., idempotency, error handling) and the return format is vague, leaving some 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?

Schema description coverage is 0%, so the description must compensate. It explains both parameters ('version' as version number, 'tag_name' as human-readable with examples), adding meaningful context beyond the schema's type and 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 clearly states the tool tags a specific version for reference, using a specific verb and resource. However, it does not differentiate from sibling tools like 'add_tag' or 'tag_document', which may have similar 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?

No guidance is provided on when to use this tool versus alternatives, nor any conditions, prerequisites, or exclusions. The description only states what it does without 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?

No annotations are provided, so the description must disclose behavioral traits. The description does not mention permanence, permissions, side effects, or irreversibility, leaving agents without critical safety information.

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 one short sentence with no wasted words. However, it could include more detail without becoming verbose. It is concise but not maximally informative.

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 a single parameter and no output schema, but it performs a destructive action. The description lacks completeness by not explaining deletion behavior, reversibility, or what happens to associated data.

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%. The description merely restates that the tool uses doc_id, adding no meaning beyond the schema. For a single parameter, the description should clarify what doc_id refers to, constraints, or examples.

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

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

The description clearly states the action (delete), resource (document), and identifier (doc_id). It is specific and distinguishable from sibling tools like list_documents or restore_version.

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?

No guidance on when to use this tool versus alternatives, prerequisites, or when not to use. The description only states the basic function without contextual advice.

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 disclose behavioral traits. It states the tool retrieves tags but does not specify whether tags are returned as an array, whether they include metadata, or any side effects. The output schema likely covers return format, but the description offers no additional 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 a single sentence of 6 words, front-loading the key information with zero waste. Every word is necessary and earns its place.

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

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

Given the complexity (simple read tool), the output schema, and the presence of many sibling tools, the description is adequate but lacks usage guidance and parameter detail. It meets minimum viability but has clear 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?

Schema description coverage is 0%, so the description should explain the doc_id parameter. It does not add any meaning beyond the parameter name; it does not specify format, source, or examples. The parameter is self-explanatory from context, but the description provides no 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?

Description clearly states the verb 'Get', the resource 'all tags', and the context 'applied to a document'. It distinguishes from sibling tools like add_tag, tag_document, and untag_document which perform different operations on tags.

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 the tool is used when you need to retrieve all tags for a document, but it provides no explicit guidance on when to use it versus alternatives such as search for tags, or any exclusions.

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

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

No annotations provided, so the description carries full burden. It only states it returns a list of relations with source/target info, missing important behavioral traits like pagination, limits, authentication needs, or 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 short but includes redundant 'Args:' and 'Returns:' sections that add no value over the schema. It could be more concise by merging the purpose line with minimal additional context.

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 has only one parameter and an output schema exists, the description covers the basics. However, it omits useful context such as whether all relation types are returned or if there are any implicit filters.

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%. The description merely paraphrases the parameter name ('entity_id: Entity ID') without adding format, constraints, or examples beyond what the schema provides.

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

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

The description clearly states the verb ('Get'), resource ('relations for an entity'), and scope ('incoming and outgoing'). It effectively distinguishes from sibling tools like 'add_relation' or 'search_graph' which have 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?

No guidance on when to use this tool versus alternatives. The description lacks context about prerequisites, filtering options, or scenarios where sibling tools might be more appropriate.

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 behavior. It only covers filtering logic and does not mention safety (read-only nature), performance implications, pagination, or authentication needs. For a read tool, it should explicitly state it is non-destructive.

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 extremely concise with three sentences. The first sentence states the core purpose, and the next two clarify filtering strategies. No unnecessary words 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?

The tool has two optional parameters, no required ones, and an output schema exists. The description covers three filtering scenarios (none, by key, by doc_id) but fails to specify the behavior when both filters are applied (e.g., conjunction or disjunction). It also omits potential ordering or limit information. The output schema may compensate for return value clarity, but behavioral context is incomplete.

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 (no descriptions in the schema). The description compensates fully by explaining the meaning of each parameter: 'Filter by key to find all values for a key' and 'Filter by doc_id to find all metadata for a document.' It adds significant semantic value 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 the tool retrieves metadata entries with optional filtering by key or doc_id. The verb 'retrieve' and resource 'metadata entries' are specific. It distinguishes itself from siblings like set_metadata (which writes) and implies a read-only 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 provides explicit guidance on when to use each filter: 'Omit both to get all metadata,' 'Filter by key to find all values for a key,' 'Filter by doc_id to find all metadata for a document.' However, it does not discuss when to avoid using this tool or mention alternatives like search.

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 disclose behavioral traits. It only states 'Get database statistics' but does not confirm read-only nature, potential side effects, authentication requirements, or any limitations. The description is too brief to provide sufficient transparency for a tool with no annotations.

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 very concise with two sentences and no unnecessary words. However, the second sentence ('Returns: Stats object...') could be integrated or expanded. It is front-loaded but could be more efficient by combining.

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

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

Given no output schema and no annotations, the description is incomplete. It does not specify what 'counts and storage info' includes, how to interpret the stats, or any caveats. For a simple tool, more context would be helpful to avoid confusion with similar siblings.

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 100% schema description coverage. According to guidelines, baseline is 3. The description adds no parameter information beyond the schema, but the return description ('Stats object with counts and storage info') provides some minimal context. No extra 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 clearly states the tool's purpose ('Get database statistics') and mentions the return type ('Stats object with counts and storage info'). However, it does not explicitly differentiate from sibling tools like query_document_stats, which may also return statistics. The verb 'get' and resource 'database statistics' are specific but lack distinguishing features.

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?

No guidance is provided on when to use this tool versus alternatives. There is no clarification of prerequisites, context, or situations where this tool is preferred or not. The description gives no usage instructions beyond the basic purpose.

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 fails to disclose important behavioral traits such as idempotency, error handling for unsupported files or empty directories, or whether ingestion overwrites existing 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 concise with two sentences, but it could be more informative without sacrificing brevity, e.g., by explaining the recursive parameter or return 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 complexity, the description is insufficient. It lacks details on behavior, error conditions, and parameter usage, even though an output schema exists. The agent has limited context to 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 description does not explain the two parameters (recursive and directory_path), and the schema has no parameter descriptions (0% coverage), leaving the agent without guidance on how to use them.

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 ingests all supported files in a directory, distinguishing it from sibling tools like ingest_file and ingest_text which handle individual files or text.

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 use this tool versus alternatives such as ingest_file, nor does it mention prerequisites or conditions for 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?

No annotations are provided, so the description must disclose behavior. It only mentions auto-detection but omits crucial details like side effects (e.g., file storage), permissions required, error handling, or processing 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?

The description is very concise with two clear sentences, no redundancy, and front-loaded key actions. Every word contributes.

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 only one parameter, no output schema, and no annotations, the description is severely incomplete. It lacks details on return values, error cases, supported file types, and processing behavior beyond auto-detection.

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%, yet the description adds no meaning to the single 'file_path' parameter. It fails to explain required format (absolute/relative), supported file types, or constraints.

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 ingests a single file and auto-detects its type (code/markdown/text). This distinguishes it from siblings like 'ingest_directory' and 'ingest_text'.

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?

No guidance on when to use this tool versus alternatives (e.g., 'ingest_directory' for directories, 'ingest_text' for raw text). The description does not mention prerequisites or exclusions.

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

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

No annotations are provided, so the description carries the full burden. It mentions ingestion but does not disclose behavioral traits such as side effects, storage location, persistence, or whether it returns any result. The type hint is mentioned but not explained in terms of 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?

The description is a single concise sentence that front-loads the action and resource. Every word is purposeful, with no wasted space.

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

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

Given no output schema, no annotations, and 0% parameter description coverage, the description is incomplete. It lacks details on return values, side effects, and prerequisites. For a tool with many siblings, more context on when to use this tool is needed.

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. It adds meaning for 'file_type' by listing possible values (code/markdown/text), but does not address the 'source' parameter at all. The required 'text' parameter is obvious from the description but lacks detail on format or constraints.

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 verb 'Ingest' and the resource 'raw text', and distinguishes from siblings like 'ingest_directory' and 'ingest_file' by specifying raw text input. It also mentions an optional type hint, adding specificity.

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 for raw text ingestion but does not explicitly state when to use this tool versus alternatives like ingest_directory or ingest_file. No guidance on prerequisites or exclusions is provided.

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, and the description does not disclose behavioral traits such as read-only nature, potential size of results, or any limits. For a list operation, it would be helpful to confirm it is safe and read-only. The description lacks such transparency.

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 sentence 'List all branches.' It is extremely concise and every word earns its place. No extraneous text. For a tool with no parameters and a straightforward function, this is appropriately sized.

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 has no parameters and an output schema exists to explain return values, the description covers the core functionality. It is complete for its simplicity, though it could mention that it returns all branches without filtering.

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 parameters, and schema description coverage is 100%. Per guidelines, 0 parameters give a baseline of 4. The description does not need to add parameter meaning since there are none.

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 'List all branches' uses a specific verb (list) and resource (branches). It clearly distinguishes from sibling tools like create_branch, switch_branch, and checkout_version, which have different purposes. The purpose is unambiguous.

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

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

The description does not provide any guidance on when to use this tool versus alternatives. However, given the tool's simplicity (no parameters) and obvious use case (viewing all branches), the usage is implicitly clear. No explicit when-not or alternative suggestions are included.

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, and the description only states the function without disclosing any behavioral traits such as rate limits, pagination, or performance implications.

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 concise sentence, front-loaded with the essential action, and contains 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?

For a simple list operation with an output schema, the description covers the core purpose, though it omits details on possible limitations like maximum results or sorting.

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 no parameters, the description adds no further detail, but the baseline for 0-parameter tools is 4, as there is nothing to clarify beyond the tool's purpose.

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 verb 'list' and resource 'all ingested documents', but does not specify what 'metadata' includes, leaving some ambiguity.

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?

No guidance on when to use this tool versus alternatives like search or search_context, which also retrieve document information.

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 provided; description lists return values (version number, timestamp, tag) but does not disclose side effects or read-only nature. For a read-only list operation, this is acceptable but incomplete without annotations.

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: one for purpose, one for return format. No wasted words, front-loaded with action.

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 purpose and return format adequately for a simple parameter-less tool. Could mention if version list is sorted or filtered, but not critical. Missing reference to time-travel concept, but 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?

No parameters exist; schema coverage is 100% (trivially). With 0 parameters, baseline is 4, and description adds no extra param info (unnecessary).

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 verb 'List' and resource 'versions of the chunks table for time-travel'. It distinguishes from sibling tools like checkout_version and restore_version which involve actions on versions.

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?

No guidance on when to use this tool vs alternatives (e.g., checkout_version, restore_version). The phrase 'for time-travel' hints at context but does not explicitly state when-not or provide comparisons.

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 present, so the description carries full burden. It mentions 'via SQL' but does not clarify whether this is a read-only operation, if it requires special permissions, or if it has side effects. The description focuses only on output, lacking behavioral 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 concise: three sentences, front-loaded with the main purpose, followed by a list of returns. It is efficient but could be slightly more structured (e.g., bullet format).

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

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

Given no parameters, no annotations, and no output schema, the description provides adequate information by enumerating the returned statistics. It is complete for a simple query tool, though the 'via SQL' phrase is ambiguous without further explanation.

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, and the schema has 100% coverage (empty). The description adds value by detailing the statistics returned, which is helpful since no output schema exists. A score of 4 is appropriate as the description compensates for the lack of parameters.

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 aggregates statistics about the document corpus via SQL, listing specific return fields. However, it does not differentiate from sibling tools like 'get_stats' or 'sql_query', which may serve similar 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?

No guidance is provided on when to use this tool versus alternatives such as 'get_stats' or 'sql_query'. There is no mention of context, prerequisites, or exclusions, leaving the agent to guess.

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 provided, so description carries full burden. It does not disclose behavioral traits such as destructiveness, reversibility, permissions, or side effects. Only states basic function.

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 sentence, concise and front-loaded. It conveys the core purpose without fluff, though it may be too brief for completeness.

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 single parameter and lack of output schema, the description is insufficient. It does not explain the implications of restoring a version (e.g., destructive, creates new version) or how it relates to sibling tools.

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 'version' is not explained beyond being an integer. With 0% schema description coverage, the description should clarify what the version refers to (e.g., document version, table schema version), but it does not.

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 action (restore) and resource (table to a specific version). However, it does not distinguish from sibling tools like checkout_version, which may have similar functionality.

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?

No guidance on when to use this tool versus alternatives like checkout_version or switch_branch. The description lacks context for appropriate 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?

No annotations provided, so description must disclose behavioral traits. It states return format (formatted string with source citations) but lacks info on read-only nature, auth requirements, rate limits, or error scenarios. For a search tool, more transparency on side effects is 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?

Description is concise (5 lines) in docstring format with clearly separated Args and Returns sections. No fluff; each 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?

Given the presence of similar sibling tools (search, search_context) and no annotations, the description adequately covers purpose, parameters, and return format. Missing some edge case details but sufficient for standard use.

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 description compensates by explaining each parameter: query as natural language, k as number of results (max 20), filters as optional JSON string. Adds meaningful context beyond schema types.

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 clearly states verb (search and return) and resource (results for LLM context building). Differentiates from siblings like 'search' and 'search_context' by emphasizing formatted output for context building.

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?

No explicit guidance on when to use this tool vs alternatives like 'search' or 'search_similar'. The description only lists parameters without context about appropriate use cases or exclusions.

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

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

The description explains the hybrid search (vector + full-text + RRF) and scope (across all chunks). With no annotations, it covers the main behavioral traits but omits details like read-only nature or performance implications.

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 main purpose. The args and returns are listed in a clear, no-waste format. 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?

Given the parameter count and presence of an output schema, the description covers purpose, parameters, and return structure. It could be more explicit about the scope (e.g., 'all chunks in the database') but 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 property descriptions are absent (coverage 0%), but the description provides clear explanations for each parameter: query as natural language, k as max 50, source_type with allowed values. This fully compensates for the missing schema 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 clearly states the tool performs hybrid search across all chunks, specifying the verb and resource. However, it does not explicitly differentiate from sibling search tools like search_context or search_similar.

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?

No guidance is provided on when to use this tool versus alternatives. The description lists parameters but does not give context or exclusions.

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

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

No annotations exist, so description carries full burden. It describes the return format and context behavior, but doesn't disclose potential side effects or safety/permission requirements. As a search tool, it's likely safe, but transparency is incomplete.

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 brief intro followed by clear Args and Returns sections. It is appropriately sized and front-loaded with the core purpose, though some sentences could be slightly 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?

With 4 params and no annotations, the description covers the tool's purpose, parameters, and return format adequately. However, it lacks explicit usage guidelines and differentiation from sibling search tools, and doesn't specify edge cases or behavior under failure.

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 adds crucial meaning: defines query as natural language, k with maximum 20, context_chunks with range 0-5, and source_type with three filter options. This compensates well for the schema gap.

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 performs search with parent/sibling/child context expansion, and lists parameters. It mostly distinguishes from basic search but doesn't explicitly differentiate from other search siblings like search_similar or retrieve_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?

It implies use when needing full context around results, but does not mention when not to use it or provide alternatives among siblings like search, search_graph, or search_similar.

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 provided, so description carries full burden. It states it returns a list of matching entities but omits behavioral details like whether the search is case-sensitive, supports pagination, or has any side effects. For a search tool, read-only nature should be 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?

Concise docstring with a one-line summary followed by Args and Returns sections. Efficiently conveys purpose and parameters with no redundant text, though could be slightly more structured for quick 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 complexity of the sibling tools (many search variants and BFS), the description lacks context on what distinguishes this from 'search', 'search_similar', or 'bfs'. Also, returns are vague ('List of matching entities') despite an output schema being present but not detailed. Incomplete for tool selection.

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?

Adds clear meaning beyond the schema: explains query is a search term, type is an optional filter, and limit max is 100. Schema only provides titles and defaults; description compensates 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?

Clearly states the verb 'Search', resource 'entities in the knowledge graph', and scope 'by name or type'. Distinguishes from sibling tools like 'search' or 'search_context' which operate on different resources.

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 parameter descriptions but no explicit guidance on when to use this tool versus alternatives like 'search', 'search_similar', or 'bfs'. The description assumes the agent knows to use it for graph entity searches, but lacks directives.

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 behavioral disclosure. It mentions the maximum k=20 and that results include scores and text snippets. However, it does not state whether the source chunk must exist, if the operation is read-only, or how results are ordered. This is adequate but not thorough.

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 purpose and is structured with Args and Returns. At 7 lines, it is reasonably concise, though the docstring format includes unnecessary line breaks. Still, 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?

Given the tool's simplicity (2 parameters, no annotations, but has an output schema), the description covers the core behavior and return structure. It could mention prerequisites (e.g., 'chunk_id must exist') or error conditions, but for a retrieval tool this is largely 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 explain the parameters. It does so clearly: 'chunk_id: ID of the source chunk' and 'k: Number of similar results to return (max 20).' This adds full semantic value beyond the schema structure.

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 'Find chunks similar to a given chunk by ID.' This is a specific verb-resource pair and distinguishes it from sibling tools like 'search' or 'search_graph' that serve 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 gives no guidance on when to use this tool versus alternatives, nor any when-not-to-use conditions. For a tool that retrieves similar chunks, it would benefit from contextual cues like 'Use for finding related content; otherwise use search for general 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?

Without annotations, the description carries full burden. It explicitly discloses overwrite behavior ('Overwrites any existing value for the same key+doc_id combination'), which is critical for a write operation. No other side effects are mentioned, but for a simple key-value set, this is sufficient.

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

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

Two sentences, front-loaded with the primary action and followed by a critical behavioral note. No extraneous information; every word 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 simple set operation with no output schema and one sibling for retrieval (get_metadata), the description covers the core behavior and scope. However, it omits potential error conditions (e.g., invalid doc_id) and side effects like versioning, which could be relevant in a document-oriented tool set.

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 description must add meaning. It explains that doc_id is optional and scopes the metadata, adding context beyond the schema's default null. Key and value are described only as 'key-value pair', providing minimal enhancement over raw schema titles.

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 clearly states the action ('Set'), resource ('metadata key-value pair'), and optional scoping ('optionally scoped to a document'). It distinguishes from sibling 'get_metadata' and other tools, providing a specific verb-resource combination.

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?

No explicit usage guidelines regarding when to use this tool vs. alternatives (e.g., 'get_metadata' for retrieval). The context is implied but not stated, leaving the agent to infer from sibling names.

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?

Discloses safety rules (blocked DELETE/UPDATE without WHERE, DROP statements), parameterized placeholders, and return format. Lacks mention of logging or other side effects but sufficient for 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?

Well-structured with sections for safety rules, examples, args, and returns. Every sentence adds value 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?

Covers all necessary aspects: purpose, safety, parameters, return format, and examples. No output schema but return described 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?

Single 'statement' parameter with examples and description of expected SQL syntax compensates for 0% schema coverage, adding meaningful guidance beyond 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 write SQL statements (INSERT, UPDATE, DELETE) with safety rails, distinguishing it from sql_query for SELECT 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 specifies when to use (write operations) and when not (SELECT queries), provides safety rules, parameterized placeholders, and examples.

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 provided, so the description carries full burden. It discloses that only SELECT queries are supported, specifies return format (columns, rows, row_count), and documents default and maximum limit. This provides adequate behavioral context for safe usage.

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 relatively long but well-organized: summary, SQL support, table list, examples, arguments, returns. Every section adds value. Could be slightly tighter, but the structure aids 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 the complexity and lack of output schema, the description fully covers purpose, allowed SQL, schema details, examples, default behavior, and return structure. An agent can confidently understand and invoke the tool without ambiguity.

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?

Input schema has 0% parameter descriptions, so the description must compensate. It details both parameters: query is an SQL SELECT string, limit has a default and max. Examples illustrate valid query syntax. This fully compensates for the schema gap.

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 runs SQL SELECT queries, lists supported SQL features, and enumerates available tables with columns. Examples further clarify usage. This distinguishes it from siblings like sql_execute.

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 limits queries to SELECT and provides examples, implicitly indicating read-only use. It does not explicitly state when not to use it or mention alternatives, but the sibling sql_execute suggests a distinction. Still clear enough for effective selection.

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 clearly states the output and that it lists all user tables. It does not mention safety or permissions, but the behavior is straightforward and non-destructive.

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 two sentences, front-loads the purpose, and contains no unnecessary words. 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?

Given no parameters and an output schema (implied), the description sufficiently explains what the tool does and what it returns. It is complete for a list 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?

No parameters exist, so the description does not need to add meaning beyond the schema. Baseline score of 4 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?

The description clearly states the tool lists all available relational tables with their schema, specifying the returned fields (table name, column name, column type, nullability). It is distinct from siblings like sql_query and sql_execute which perform 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?

No explicit guidance on when to use this tool vs alternatives is given. Usage is implied as a discovery tool, but no exclusion criteria or context is provided.

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 exist, so the description bears full responsibility for behavioral disclosure. It only states the action without explaining side effects, such as whether the current working context changes or if any state is modified. This is insufficient for an agent to understand the 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?

The description is very short at six words, but it omits critical context. It is not appropriately sized for the complexity; a few more sentences would improve usability without losing 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?

Given the lack of output schema, annotations, and parameter details, the description fails to provide complete context. An agent cannot determine return values, error conditions, or the effect of switching branches.

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%, and the description does not add any meaning to the 'branch_name' parameter beyond its name. It fails to specify constraints like valid values, format, or required permissions.

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 specifies a clear verb 'Switch' and resource 'branch', but does not differentiate from sibling tools like 'checkout_version' or 'create_branch'. It gives the basic purpose without context on how it differs.

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?

No guidance is provided on when to use this tool versus alternatives. The description lacks any context about prerequisites, typical use cases, or exclusions.

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

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

Discloses idempotency, which is useful. No annotations provided, so the description carries the burden. Lacks details on scope, safety, or potential side effects beyond the sync operation.

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

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

Two short sentences, front-loads the main purpose, then gives usage context. No wasted words.

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 no parameters and no output schema, the description captures purpose and usage adequately. Could mention prerequisites or error handling, but not essential.

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?

No parameters exist, so the description cannot add parameter information. Schema coverage is 100% by default, so baseline 4 is appropriate. The description does not need to explain parameters.

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?

Clearly states the tool syncs data from LanceDB vector store into relational tables. Distinguishes from sibling ingest/query tools by specifying 'after ingesting documents to make relational queries up to date'.

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 recommends calling after ingestion and notes idempotency allows anytime use. Does not specify when not to use, but the idempotent nature makes it safe.

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 only discloses the 'creates if not exists' behavior, but omits details such as idempotency, return values, permissions, or error conditions.

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, efficient sentence with no wasted words, directly conveying the core action and a key behavioral trait.

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 no output schema and no annotations, the description is minimally adequate but lacks disambiguation from sibling tools and details like return values or idempotency, leaving gaps in completeness.

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%, and the description adds no meaning or constraints to the parameters (doc_id, tag), leaving their formats, validation rules, or usage unclear.

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 applies a tag to a document and creates the tag if it doesn't exist, specifying the verb, resource, and additional behavior that distinguishes it from sibling tools like add_tag or create_tag.

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 use this tool versus alternatives like add_tag, create_tag, or untag_document, nor does it mention prerequisites or 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?

No annotations are present, so the description must convey behavior. 'Remove a tag' implies a destructive update, but there is no disclosure of side effects (e.g., document modification), error handling for missing tags, or authorization requirements.

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 very short (6 words) with no wasted words, but it omits critical details that could be added without bloat. It is minimally adequate but not optimally structured for agent decision-making.

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

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

Given no output schema, 0% schema coverage, and only 2 parameters, the description is too sparse. It does not specify return values, error cases, or success criteria, making it incomplete for a tool requiring parameter understanding.

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%, and the description adds no parameter-specific meaning. The parameters doc_id and tag are merely named without any explanation of their format, constraints, or semantics.

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 action 'Remove a tag from a document', using a specific verb and resource. It distinguishes itself from sibling tools like add_tag and tag_document, which perform the opposite 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?

No guidance is provided on when to use this tool versus alternatives, such as add_tag or other document mutation tools. There is no mention of prerequisites (e.g., tag must exist) or context for appropriate use.

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