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

No annotations are provided, so the description bears full responsibility for disclosing side effects. It states 'Create a new knowledge fragment file' which implies writing to disk, but omits critical details: whether existing files are overwritten, path validation, directory creation, permission requirements, or failure modes. 'Proper frontmatter' is vague and does not explain how inputs map to frontmatter or what validation occurs.

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, front-loaded with the action ('Create a new'), and every word contributes meaningful information. No redundant phrasing or fluff. It is appropriately sized for the tool's complexity.

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 a rich schema, the description lacks essential operational context. There is no output schema, annotations are absent, and the description fails to explain success/failure behavior, path constraints, prerequisites, or how the tool integrates with the knowledge base system. The 'frontmatter' mention hints at internal structure but is insufficient for a 7-parameter creation tool.

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

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

Schema description coverage is 100% for all 7 parameters, so the schema already provides detailed parameter meanings. The description adds only the concept of 'frontmatter' as context but does not clarify how specific parameters map to frontmatter fields or their relationships. With full schema coverage, baseline 3 is appropriate; the description adds minimal 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 verb 'Create' and the resource 'knowledge fragment file', making the action unambiguous. The word 'new' distinguishes this from update_knowledge and delete_knowledge, and 'frontmatter' adds context about the file structure. This is a specific, non-tautological statement that fully conveys the tool's purpose.

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

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

The description implies when to use this tool (when creating a new knowledge fragment) and the 'new' distinguishes it from update/delete operations. However, it does not explicitly exclude alternatives or name them, falling short of the highest standard. The context from sibling names clarifies the use case but the description itself lacks direct comparison.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior. It does not state whether the operation is read-only or has side effects, what the output/report format is, or whether any permissions are required. The word 'validate' implies a check but the concrete behavior remains underspecified.

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, clear sentence that is front-loaded and contains no fluff. Every word contributes to the purpose, making it highly efficient.

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, no annotations, and no output schema, the description is minimal. It conveys the action and scope but omits expected outputs, safety profile, and any conditions that might trigger use. While simplicity helps, an audit tool would benefit from explaining what the validation result looks like or if it's safe to run.

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 zero parameters, so the input schema fully covers everything. According to the rubric, 0 params earns a baseline of 4, and no extra description is needed for parameter 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 uses a specific verb ('Validate'), specifies the resource ('knowledge fragments'), and clarifies scope ('all') and the focus ('broken refs and related links'). This clearly distinguishes it from sibling tools like search, add, or delete operations.

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, when not to use it, or any alternatives. It doesn't mention prerequisites, typical scenarios, or relation to other tools such as update_knowledge or reload_sources.

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 explicitly notes that deletion is 'permanent,' which is the most critical side effect for a delete operation. However, it does not mention other potential effects such as cascading deletions or permission requirements, preventing a higher score.

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, succinct sentence that is front-loaded with the action and resource. Every word earns its place, with no redundant information or filler.

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

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

For a simple one-parameter delete tool, the description is adequate but lacks information about return values or error handling, especially given the absence of an output schema and annotations. It does not fully cover what the agent should expect after execution, but it is sufficient for the basic operation.

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

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

Schema coverage is 100% because the single parameter 'path' has a descriptive explanation with an example. The tool description adds no additional parameter information, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Delete') and resource ('knowledge fragment'), clearly indicating the action. It also adds 'permanently' to convey irreversibility, distinguishing it from sibling tools like update_knowledge or add_knowledge.

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 explicit when-to-use guidance or alternatives. It simply states what the tool does, leaving the agent to infer usage from the tool name and siblings. There is no mention of prerequisites or when to choose this over update_knowledge.

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 transparency burden. It clearly indicates read-only behavior ('List') and scopes to 'all loaded' sources, implying no filters. It also discloses the output content (aliases, paths, fragment counts), which is useful given the lack of an output schema.

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, tightly worded sentence that front-loads the action and resource. Every word adds value, and it is appropriately concise for a parameterless list operation.

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

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

Given the low complexity (no parameters) and the absence of an output schema, the description is complete: it tells the agent what the tool does, the scope ('all loaded'), and what will be returned (aliases, paths, fragment counts). No additional context seems necessary.

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 zero parameters, so the baseline of 4 applies. The description adds nothing about parameters, but none are needed, and the schema coverage is trivially 100%.

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 loaded knowledge sources, a specific verb and resource, and differentiates from siblings like list_tags (tags vs. sources) and search_knowledge (search vs. list). It also specifies the returned details (aliases, paths, fragment counts).

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 search_knowledge or list_tags. The description implies usage for obtaining an overview, but does not mention conditions, exclusions, or specific contexts.

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 implies a read-only operation but does not explicitly state safety, authentication requirements, or output format details. 'All available' is ambiguous (all user tags vs. all system tags) and there is no mention of ordering, pagination, or rate limits.

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

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

The description is a single sentence that is direct and without redundancy. It conveys the essential purpose and one key output detail efficiently.

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

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

For a zero-parameter list tool, the description covers its primary function and a key output detail. However, without annotations or an output schema, the agent must guess whether tags are returned with additional metadata, and the description does not mention ordering or exact response shape, 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?

The tool has zero parameters, and the schema coverage is 100% (vacuously). The description adds value by indicating that the response includes fragment counts, but with no parameters to clarify, the baseline of 4 applies for the zero-param case.

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 the resource 'knowledge tags', and adds the detail 'with fragment counts', which defines the tool's specific scope. It distinguishes itself from sibling tools like list_sources (sources vs. tags) and search_knowledge (search vs. list).

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 like search_knowledge or list_sources. There is no mention of use cases, prerequisites, or exclusions, leaving the agent to infer that it is for browsing tags rather than searching or managing them.

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

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

No annotations are provided, leaving the description to carry the full behavioral burden. It only says 're-discover' without disclosing side effects, safety implications, reversibility, or what happens to existing sources. This is a significant gap for a state-modifying 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?

The description is two sentences long, front-loaded with the core action, and every word contributes. It is a model of conciseness without sacrificing necessary 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's simplicity (no parameters, no output schema), the description covers the essential purpose and usage scenario. However, it omits behavioral details like return value or side effects, though this is partially addressed under behavioral transparency. Overall, it is complete enough for a minimal tool.

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

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

The tool has zero parameters, so the schema is trivially complete (100% coverage). The description adds no parameter-specific information, which is appropriate since there are no parameters to explain. Baseline for zero parameters is 4.

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 function with the verb 're-discover' and resource 'knowledge sources from config', setting it apart from sibling tools like search_knowledge and list_sources. The action is specific and 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 phrase 'Use after modifying ~/.knowledgebased.json' provides a clear contextual trigger for when to use the tool. It does not mention alternatives or exclusions, but the context is sufficient for a parameterless reload command.

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

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

No annotations are provided, so the description carries the full burden. It discloses the key behavior of graph traversal and that it 'Returns raw fragment contents' (as opposed to summaries). However, it does not explicitly state read-only status, potential side effects, or limits on hops, though these are less critical for a search tool. The added behavioral context goes beyond the schema's structural details.

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

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

The description is three sentences long, with the first sentence front-loading the core purpose, the second giving immediate usage context, and the third providing alternative tool guidance. Every sentence earns its place with no redundancy or fluff.

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

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

Given that there is no output schema, the description's statement about returning raw fragment contents is helpful, though it could be more specific about the output structure. It covers purpose, usage, alternatives, and the meaning of 'raw' relative to other tools. The schema covers parameter details, and the description sufficiently integrates with sibling tools for a complete picture.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds some nuance, such as 'exact tags' implying precision and 'graph traversal' relating to the hops parameter, but it does not substantially enhance understanding beyond what the schema already describes. The schema's descriptions for hops and output are already clear.

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 function: 'Search knowledge fragments by tags with graph traversal. Returns raw fragment contents.' This specifies the verb (search), resource (knowledge fragments), and method (tags + graph traversal). It also distinguishes itself from sibling tools by explicitly contrasting with search_rag (which summarizes) and search_semantic (which explores coverage).

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

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

The description provides explicit usage guidance: 'Use this when you know the exact tags and need full, unabridged content for a specific domain.' It also names alternatives and when to prefer them: 'Prefer search_rag over this for answering questions' and 'Prefer search_semantic over this for exploring what the knowledge base covers.' This is exemplary differentiation.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the two-tier result generation process: high-confidence fragments returned verbatim, lower-confidence documents synthesized via LLM sampling. This is meaningful behavioral context. It does not explicitly state that the tool is read-only, but the semantics imply it, and no annotation contradiction exists. A score of 4 reflects strong transparency without additional side-effect details.

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

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

The description is three concise sentences with no fluff. It front-loads the core function in the first sentence, then provides usage guidance and alternatives in the following sentences. Every sentence contributes value, making it efficient and well-structured.

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?

No output schema is provided, so the description must convey return behavior. It explains the output type ('concise, ready-to-use answers') and the verbatim vs. summary distinction. It also covers when to use the tool and the role of parameters. It lacks explicit return format details, but for selection and invocation, this is sufficient. A 4 reflects that it is almost complete without specifying exact output structure.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds conceptual meaning to the thresholds: directThreshold maps to 'High-confidence results are returned verbatim' and threshold relates to 'lower-confidence ... synthesized into a query-aware summary.' This helps an agent understand the role of each scoring parameter beyond the schema descriptions, meriting a 4.

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 function: 'Semantic search with automatic summarization.' It distinguishes itself from sibling tools by explicitly referencing search_semantic and search_knowledge, and clarifies its unique behavior of returning verbatim results for high-confidence matches and synthesized summaries otherwise. This makes the purpose 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 provides explicit usage guidance: 'Use this when answering user questions' and directly contrasts with alternatives: 'Prefer search_semantic over this when exploring... Prefer search_knowledge over this when you need full unabridged content.' This clearly indicates when to use this tool and when not to.

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

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

No annotations are provided, so the description carries the burden of disclosing behavior. It mentions that results include similarity scores and that it is semantic search, which implies a read-only operation, but it does not explicitly state that it makes no modifications or mention any side effects. It also lacks details on auth, rate limits, or data scope. This is adequate but not comprehensive.

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: two sentences that immediately state the core function and then provide usage guidance. Every word earns its place, with no redundancy or filler. It is well-structured with the main purpose first and secondary guidance second.

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?

Context is complete for a search tool: it covers purpose, usage scenarios, and key outputs (similarity scores). Although there are no annotations or output schema, the description effectively compensates by explaining the nature of results and providing clear alternatives. It could mention side effects explicitly, but for a read-only search operation, the current description is sufficient.

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

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

Schema description coverage is 100%, so the schema already explains all parameters. The description adds some context by mentioning 'raw fragment content with similarity scores' (related to threshold) and 'natural language queries in any language' (query), but it does not add new meaning for topK or output beyond the schema. This meets the baseline of 3 given full schema coverage.

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

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

The description clearly states the tool performs semantic search across knowledge fragments using embeddings, with support for natural language queries in any language. It explicitly differentiates from search_rag by noting when to use this tool (exploring coverage or raw fragments with similarity scores) versus search_rag for answering questions.

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: 'Use this for exploring what the knowledge base covers or when you need raw fragment content with similarity scores. Prefer search_rag over this for answering user questions.' This clearly indicates when to use this tool and names the alternative, making it easy for an agent to choose correctly.

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

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

With no annotations, the description must carry the burden of behavioral disclosure. It only states that it updates fields, but does not disclose that provided fields replace existing values (as noted in the schema), nor does it mention effects on unprovided fields, permissions, or return behavior. This is a significant transparency gap for a mutation tool.

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

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

The description is a single, front-loaded sentence with no unnecessary words or filler. It effectively communicates the tool's primary action and target in a compact form.

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 schema provides rich parameter context, but the description omits two updatable fields (title, refs) and lacks any guidance on usage scenarios or side effects. For a tool with six parameters and no output schema, this description is adequate but not fully complete. It is less bare than a pure tautology but still leaves 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 100%, giving detailed explanations for all six parameters. The description itself adds minimal semantic value, only listing three of the six fields. Baseline 3 is appropriate because the schema does the heavy lifting, and the description does not contradict or enhance it.

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

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

The description clearly states the verb 'Update' and the resource 'existing knowledge fragment', and specifies the modifiable attributes (content, tags, related links). This distinguishes it from sibling tools like add_knowledge and delete_knowledge. Although it omits title and refs from the list, the core 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 implies usage for existing fragments via the word 'existing', but it does not explicitly state when to use this tool versus add_knowledge or delete_knowledge, nor does it mention any prerequisites or exclusions. The intended context is inferable but not explicitly articulated.

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