V.I.S.O.R.

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

No annotations are provided, so the description carries full burden. It mentions 'via the UI', hinting at an interaction method, but does not disclose side effects, required permissions, or whether the operation is reversible. For a tool that likely creates a resource, more behavioral details 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 concise (one sentence) but at the expense of clarity and completeness. It is not well-structured; it lacks logical breakdown and front-loads a confusing phrase. Conciseness without substance is not effective.

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 4 parameters (3 required) and no schema descriptions, the description is far too minimal to be complete. Even though an output schema exists, the description fails to provide necessary context for selecting and invoking the tool.

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

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

Schema description coverage is 0%, meaning the schema has no descriptions for parameters. The description does not explain any of the four parameters (name, description, content, strategy). The agent gets no added meaning beyond 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 states 'Adds a newly created custom skill via the UI', which identifies the resource (custom skill) and action (adds), but the phrase 'newly created' is confusing—it implies the skill was already created elsewhere, contradicting the action of adding. It does not distinguish from sibling tools like 'delete_custom_skill' or 'list_custom_skills'.

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. No context about prerequisites, scenarios, or exclusions 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?

Despite no annotations, description discloses combination of four signals, token budget cap of 8,000 tokens, and return of scored code nodes. Does not mention side effects, auth needs, or rate limits, but as a context-building tool, these are less critical.

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, uses bullet points for signals, and front-loaded with bold title. However, example is incomplete (no output shown) and skill parameter is missing, slightly reducing efficiency.

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?

Tool complexity is moderate with 2 parameters and output schema. Description explains core functionality well but omits documentation for 'skill' parameter, leaving a gap 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?

With 0% schema description coverage, description must compensate. 'query' is well-described as natural language query, but 'skill' parameter is entirely undocumented in both schema and description, leaving its purpose unknown.

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 it builds a ranked context payload from natural language queries using multiple signals, distinguishing it from simpler sibling tools like search_codebase. However, it does not explicitly contrast with all siblings.

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

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

Description implies usage for generating LLM context and provides an example, but lacks explicit guidance on when to use this tool versus alternatives (e.g., search_codebase, get_file_context) and when not to use it.

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

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

With no annotations, the description bears full transparency burden. It discloses the operation (read-only analysis) and the filtering criterion (in-degree 0), but does not mention prerequisites, side effects, or performance implications. Adequate but not detailed.

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 with the core action. Every word is meaningful, leaving no waste.

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

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

Given an output schema exists (though not shown) and no parameters, the description is mostly complete. It explains what the tool does, though it could benefit from mentioning the context (code dependency graph). Still, it is sufficient for an agent to understand the basic 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?

There are zero parameters and schema coverage is 100%. According to guidelines, zero parameters yields a baseline of 4. The description adds no parameter info, but it is 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 tool finds nodes with in-degree 0 (no incoming callers), using a specific verb and resource. This distinguishes it from sibling tools like impact_analysis or get_dependency_chain by specifying the exact criterion.

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 when to prefer it over get_dependency_chain or search_codebase. The description 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?

No annotations exist, so the description must fully disclose behavioral traits. It merely states 'Deletes a custom skill' without indicating irreversibility, side effects, or permission 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 extremely short, consisting of one brief sentence. While front-loaded, it lacks substantive content to justify its brevity.

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 delete tool with one parameter and no annotations, the description provides minimal context. It fails to clarify return values, error conditions, or scope of deletion.

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

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

The input schema has 0% description coverage, and the tool description adds no meaning to the 'skill_id' parameter 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 'Deletes' and resource 'custom skill'. This is sufficiently distinct from siblings like 'add_custom_skill'.

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 vs. alternatives (e.g., hiding a skill or deactivating it), nor any prerequisites.

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

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

With no annotations, the description should disclose behavioral traits. It does not mention whether the operation is read-only, has performance implications, or any side effects. The statement only covers return value, leaving important behaviors implicit.

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, no unnecessary words. It is concise, though it might benefit from slightly more structure (e.g., separating purpose and output 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?

Despite having an output schema, the description does not elaborate on the returned graph structure (e.g., nodes, edges, properties). Given the complexity of a 'graph topology', the description is too minimal to fully inform the agent about the response.

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 single parameter 'depth' has no description in the schema (0% coverage) and the tool description does not explain what depth controls or how it affects the output. The default value of 1 is noted, but its semantic meaning is absent.

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 ('Returns'), resource ('CodeNode graph topology'), and output format ('as a JSON string'). It is specific and distinct from sibling tools, which focus on other code analysis 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 (e.g., get_dependency_chain or get_symbol_context). The description only states what it does, without context on 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?

With no annotations, the description discloses key behaviors: it traverses the import graph, uses BFS, and has a max depth of 5. However, it omits whether the tool is read-only, handles circular dependencies, or any authentication or performance constraints. These gaps limit 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 concise at 8 lines, with clear separation of purpose, usage hint, and parameter explanation. It avoids unnecessary fluff. The structure is front-loaded with the core action, making it quick 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?

Given that an output schema exists (not shown), the description doesn't need to detail return values. However, it lacks information on failure conditions (e.g., symbol not found), handling of circular dependencies, or scope of 'import edges graph' (e.g., only Python imports?). This makes it somewhat incomplete for a complex tool.

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

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

Schema coverage is 0%, so the description must compensate. It explains 'symbol' as 'Name of a class or function. Its source file becomes the root of the BFS traversal.' This adds significant meaning beyond the raw schema, though it could clarify if it requires fully qualified names or module paths.

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 'traverses the import edges graph ... and returns the full transitive dependency chain', specifying a verb and resource. It distinguishes from siblings like 'get_architecture_map' or 'get_drift_report' by focusing on dependency chains. However, it could be more explicit about the exact type of dependencies (e.g., file-level only).

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 use case example: 'What does auth.py ultimately depend on?' which implies when to use. But it offers no guidance on when not to use this tool or alternatives among the listed siblings like 'get_architecture_map' for higher-level views, or 'impact_analysis' for change effects.

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 details how detection works (comparing hashes or timestamps) and implies read-only access. No contradictions exist, but it omits potential side effects or prerequisites like indexing.

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, with a brief purpose statement, clear mode descriptions, and a parameter list. Every sentence adds value without redundancy, making it efficient for an AI agent 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?

Given the tool's complexity (two modes, 3 parameters), the description is fairly complete. It explains detection logic and parameter semantics, but does not mention the output format (though an output schema exists) or prerequisites like indexing. Overall, it meets the minimum for effective 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?

The schema has 0% description coverage, so the description must add meaning. The Args section provides clear explanations for all three parameters (context_files, loaded_at, file_hashes), including types and purpose, which 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 the tool detects context drift between an AI's snapshot and the current codebase, using a specific verb ('detects') and resource ('context drift'). While it does not explicitly distinguish from sibling tools, the purpose is unambiguous and matches the tool's name.

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 two modes of operation (hash-based preferred, timestamp-based fallback) and hints at when to use each. However, it lacks explicit guidance on when not to use the tool or how it compares to siblings, leaving some ambiguity for the agent.

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 discloses the return type and content, but doesn't mention side effects (e.g., readonly), permissions, or indexing requirements. 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?

Single 18-word sentence that efficiently conveys purpose and output. No wasted words, front-loaded with key action and result.

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 existence of output schema, description provides sufficient high-level overview. Mentions specific content (symbols, line ranges). Slightly more context about indexing or environment would improve 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%, yet the description adds no details about the 'path' parameter beyond the schema. It does not specify format, constraints, or examples, failing to compensate for low 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 returns a structured AST summary for a given file, listing included symbols and line ranges. The verb 'returns' and specific resource 'file' make purpose unambiguous, distinguishing it from sibling tools like 'get_symbol_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?

No explicit guidance on when to use this tool versus alternatives like 'get_symbol_context' or 'search_codebase'. The description only implies usage for file analysis but lacks context on prerequisites or typical scenarios.

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 full burden. It mentions 'indexed' which implies a prerequisite but does not disclose whether the operation is read-only, any auth requirements, or behavior when symbol is not found. It is adequate but could be more 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 highly concise: one sentence for the core purpose, one line for example usage, and a brief parameter description. No unnecessary words, and front-loaded with key 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?

The description covers the main purpose and usage. Although it could mention limitations (e.g., only for indexed code) or behavior for multiple matches, the presence of an output schema reduces the need for return value details. It is nearly complete for the tool's complexity.

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 schema description coverage at 0%, the description adds significant meaning: it explains that 'symbol' can be exact or partial, and lists the types of symbols (class, function, import). This fully compensates for the lack of 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 that the tool returns indexed AST nodes matching a symbol name, including file path, node type, and line range. This is a specific verb-resource combination and distinguishes it from siblings like 'get_file_context' (focuses on a file) and 'search_codebase' (broader search).

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 an example question ('Where is VectorDBClient defined?') that implies when to use the tool. However, it does not explicitly state when not to use it or compare to alternatives, though the context of siblings provides some implicit guidance.

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

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

No annotations are provided, so the description must disclose behavioral traits. It only states 'returns' but does not indicate read-only nature, side effects, permissions, or rate limits. This is insufficient for 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 brief with two sentences, front-loading the action. It is concise but could be slightly more structured. No unnecessary 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?

Given no parameters and an output schema (not shown), the description lists three fields but does not confirm completeness or explain corner cases. For a simple getter, 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?

There are zero parameters, so the schema coverage is 100%. The description adds value by listing the specific data fields returned, which helps the agent understand the output beyond empty 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 'Returns the current state of telemetry data' with specific fields listed (graph_nodes, context_burn, drift_alert). However, it does not explicitly differentiate from sibling tools like get_architecture_map or get_drift_report, which is a minor gap.

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. No context about prerequisites or typical scenarios 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?

No annotations are provided, so the description carries the full burden. It states that it confirms the server is alive, but does not disclose what it returns or any side effects. For a simple health check, 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 a single sentence that is front-loaded and contains no wasted words. It is concise and to the point.

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, straightforward purpose) and the existence of an output schema, the description is complete enough. No additional information 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?

There are no parameters, so the description does not need to add meaning beyond the schema. Baseline is 4, and the description adds no unnecessary detail.

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

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

The description clearly states it is a basic health-check endpoint confirming server liveness. The verb is 'health-check' and the resource is the server. It is distinct from sibling tools, which focus on custom skills, code analysis, etc.

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 for checking server availability. There are no explicit when-not or alternatives, but given the simplicity and lack of sibling overlap, the usage context is clear.

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

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

No annotations exist, so the description must carry all behavioral information. It mentions BFS and depth limit (5), which provides some insight, but does not disclose error handling, output format, or read-only status. The behavior is partially 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 a single, focused sentence with no redundant information. It efficiently communicates the core purpose and constraints.

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 (not provided) and a single parameter, so the description is reasonable but omits important usage context like prerequisites or when to choose this over similar 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?

Schema description coverage is 0%, so the description should compensate. The sole parameter 'file_path' is not elaborated upon; only inferred from tool context. The description does not explain what constitutes a valid path or how it relates to the change.

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 ('Fetch'), the resource ('downstream dependent files'), and the method ('BFS max depth 5'). It distinguishes from sibling tools like 'get_dependency_chain' and 'trace_route' by specifying direction and traversal method.

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_dependency_chain' or 'trace_route'. The description lacks conditions or exclusions 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?

With no annotations, the description bears full responsibility for behavioral disclosure. It accurately describes a read-only listing operation, though it could explicitly state that no modifications are made.

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 that is concise and front-loaded with the key action and object. No unnecessary 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?

Given the tool's simplicity (no parameters, straightforward purpose, and an output schema available), the description is complete enough for an AI agent to understand 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 tool has no parameters, so the input schema is complete. The description does not add parameter-specific details, but the baseline for zero parameters is 4 per the guidelines.

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 lists custom V.I.S.O.R architecture skills, using a specific verb and resource. It is easily distinguishable from sibling tools like add_custom_skill and delete_custom_skill.

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 guidance on when to use this tool versus alternatives, nor does it specify any prerequisites or exclusions. For a simple listing tool, this is adequate but leaves some ambiguity for an AI agent.

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 only states 'search' and 'returns list', omitting details like whether it is read-only, required permissions, rate limits, pagination, or sorting 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 concise with a single sentence, but it sacrifices completeness for brevity. It is front-loaded with the core action, but lacks depth for a tool with minimal other documentation.

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 an output schema, the description could rely on it for return values, but it does not explain what the 'list of nodes' contains. With multiple sibling tools, the description should provide more context to help agents choose 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%, yet the description does not add any meaning to the 'query' parameter. It fails to describe the expected input format, constraints, or how the semantic search works, leaving agents without crucial guidance.

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 'semantic vector search across CodeNodes' and returns a list of nodes. This provides a specific verb and resource, distinguishing it from siblings like dead_code_detection or get_dependency_chain. However, it does not explain what 'CodeNodes' are, which slightly reduces clarity.

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. The description does not mention when-not-to-use, prerequisites, or which sibling tools might be better suited for different search needs.

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

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

With no annotations provided, the description carries full burden. It mentions controlling and highlighting but does not disclose whether the operation is read-only, has side effects, or persists across sessions. The clearing behavior is noted, but overall behavioral transparency is minimal.

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. It includes actionable instructions and example. Minor redundancy ('Directly controls' and 'real-time 3D visual feedback') slightly reduces efficiency.

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 control tool with two required parameters, the description covers both and explains the clearing behavior. Given that an output schema exists (though not detailed here), the description is sufficiently complete to guide the agent.

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 explain parameters. It describes file_paths as absolute or relative paths and intent as a concise 2-4 word description. This adds meaningful context beyond the raw schema, though relative path handling could be more explicit.

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 controls the V.I.S.O.R Developer HUD to highlight files, with specific verb 'controls' and resource 'HUD'. It distinguishes from siblings like search_codebase or build_context by focusing on visual feedback during reasoning.

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 suggests using sequentially during investigation and describes clearing with empty list. However, it does not compare to alternatives or state when not to use, leaving the agent to infer usage 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 provided, so description carries full burden. It says 'persists' indicating a write operation but doesn't disclose idempotency, overwrite behavior, or side effects. Lacks details about embedding process.

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, front-loaded with key verb. Could be slightly more detailed but remains concise 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?

Tool has an output schema but description doesn't mention return value. With 2 simple params and no annotations, the description provides the bare minimum. Lacks behavioral details and parameter guidance.

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?

Both parameters (role, content) are not described in the description. Schema description coverage is 0%, and the description adds no meaning beyond the schema types. The agent has no guidance on expected values or format.

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 'persists' and the resource 'agent conversation turn' with additional detail about embedding and local DB. This distinguishes it from sibling tools which are mostly code analysis 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?

No guidance on when to use or not use this tool vs alternatives. No context about prerequisites or typical scenarios.

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 behavior. It only states 'trace a path' without explaining what that entails (e.g., steps, time complexity, side effects) or what the output contains, despite an output schema being available.

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 at one sentence, but it sacrifices necessary detail. It is not verbose, but the brevity leads to under-specification.

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 schema descriptions and annotations, the description is insufficient. It does not cover what the tool returns, the nature of the nodes/paths, or any usage context, leaving the agent with too many unknowns.

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 elaborate on the source and target parameters beyond their names. No additional semantics or constraints are 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?

The description clearly states the action (trace) and the objects (path between source and target nodes). It effectively communicates the core functionality, though it could be more specific about the domain (e.g., dependency graph).

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 trace_route versus sibling tools like get_dependency_chain or impact_analysis. The description lacks context on prerequisites or limitations.

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