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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It only states that the tool adds a fact and returns the created fact dict. It does not mention idempotency, duplicate handling, validation rules, side effects, or any potential non-obvious behavior. For a mutation tool, this is a significant gap.

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

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

The description is structured as a parameter list with examples, making it easy to scan. While it is long (necessary for 14 parameters), each line contributes value. It is front-loaded with the core purpose. No fluff or redundant content.

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 (14 parameters, no output schema, no annotations), the description covers parameter semantics and the return type. It does not explain error conditions, authentication, or integration with other tools, but for a single-fact add operation, it provides sufficient context for correct invocation.

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

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

Schema description coverage is 0%, so the description fully compensates. It provides detailed, example-rich explanations for all 14 parameters, including formats for dates, confidence ranges, and source fields. This adds substantial meaning beyond the schema titles and 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?

The description clearly states 'Add a new fact (subject-predicate-object triple).' This is a specific verb with a well-defined resource and data structure. It distinguishes itself from siblings like `add_facts_batch` through the singular 'a new fact' vs. batch, and the explanation of the triple format.

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 adding a single fact, but does not explicitly state when to choose this tool over `add_facts_batch` or other fact-related tools. There is no mention of conditions, prerequisites, or exclusions. It is clear what the tool does, but alternative routing is absent.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It explicitly states that each fact is committed independently, which is critical for understanding partial-failure semantics, and describes the return summary (added count, duplicates count, errors). It does not cover permissions, rate limits, or duplicate detection criteria, but the core behavior is disclosed. The description adds meaningful context that is not present in the schema or 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 concise and well-structured. The opening sentence states the core purpose immediately, followed by an 'Args' section listing the fields in a clear bullet-like format, and a 'Returns' section describing the output. Every sentence earns its place; there is no fluff or repetition. The information is front-loaded and easy to scan, making it efficient for an 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 minimal schema and lack of an output schema, the description provides the necessary context: the fact field structure and the return summary. It covers the independent-commit behavior and the counts/errors in the response. It does not explicitly address error scenarios (e.g., what happens if a single fact fails) but the return summary implies partial success. The description is largely self-contained and sufficient for correct invocation, though it might benefit from clarifying how duplicates are identified and whether there is any limit on batch size.

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 is minimal, only specifying 'facts' as an array of objects with additionalProperties true, giving 0% coverage. The description compensates by enumerating the expected fields (subject, predicate, object required; plus optional fields like subject_type, context, etc.) and clarifying that they match add_fact's structure. It provides meaning beyond the schema, though it does not explain each field's type or constraints, relying on a reference to add_fact. This is sufficient context for an agent to construct valid input.

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: 'Add multiple facts, committing each newly created fact independently.' It specifies the exact action (adding multiple facts), the resource (facts), and a key distinguishing behavior (independent commits). This separates it from the sibling add_fact, which handles a single fact. The verb and resource are precise, making the tool's role 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 this tool is for adding multiple facts at once, but it does not explicitly contrast with add_fact or state when to choose one over the other. There is no mention of 'use this when you need to add several facts in one call' or any alternative or exclusion criteria. The context is present but not made explicit, so an agent must infer the usage scenario. It is not misleading, but it could be stronger.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly describes the return behavior: returns the created entry dict on success, or an error dict for blank or duplicate input. This goes beyond a simple statement of the action and gives the agent specific expectations about outcomes and error cases. It could mention other validation constraints, but the disclosed information is already valuable.

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 efficient and well-structured. It leads with the action, then lists parameters with concise definitions, and ends with return behavior. There is no redundancy; every section serves a purpose. The formatting using 'Args:' and 'Returns:' makes it easy to scan.

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

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

For a simple add operation, the description is complete. It covers all five parameters, including which are required (three required) via the schema, and explicitly notes return behavior and error conditions. No output schema exists, so the return description is necessary and sufficient. There is no mention of prerequisites or side effects beyond what is relevant for this 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 description coverage is 0%, so the description is the only source of parameter meaning. It explains every parameter with concrete examples (e.g., term: 'USAF', expansion: 'United States Air Force'), and clarifies that domain and aliases are optional. This fully compensates for the absent 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 states exactly what the tool does: 'Add a new glossary entry.' This is a specific verb+resource pair that distinguishes it from siblings like add_fact or update_glossary_entry. The purpose is unambiguous and clearly scoped to glossary entries.

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 (when you want to add a glossary entry) but does not explicitly guide the agent on when to choose this tool over alternatives. For instance, it does not mention that update_glossary_entry should be used for existing entries. The only guidance is the verb 'Add', which is implied rather than explicit.

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 of behavioral disclosure. It does make clear this is a read-only check operation that 'Returns breakdown of source statuses,' which suggests no mutation. However, it does not disclose what happens for a nonexistent fact_id, whether the operation has side effects on source statuses, or any performance/runtime characteristics. The return type is named but its fields are not described.

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

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

The description is compact and economically formatted with standard Args/Returns sections. Every sentence serves a purpose, and the core action is front-loaded in the first line. It avoids fluff, though the 'Returns:' line repeats the already-stated 'breakdown' concept rather than adding new 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 single-parameter tool, the description covers the input, the general behavior, and names the return type. It does not define what 'IntegrityCheckResult' contains beyond a 'source status breakdown,' and given the existence of three closely-related source tools, it could benefit from clarifying its scope relative to them. It is adequate but leaves ambiguity about what 'integrity' means operationally.

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 the schema only says 'Fact Id' with no description. The description compensates partially by stating 'fact_id: Fact UUID string,' adding that the value is a UUID and identifies the fact whose sources are checked. This adds modest meaning beyond the bare schema, but is thin — it doesn't state constraints on format beyond the label 'UUID string' or clarify what 'integrity' will be computed against.

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

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

The description states a clear verb+resource pair: 'Check integrity of a specific fact's sources.' It identifies the domain (facts and their sources) which helps distinguish it from unrelated siblings like list_tags or create_note. However, the term 'integrity' is vague without defining what metric is examined, and the tool's relationship to closely-related siblings (get_facts_with_stale_sources, revalidate_fact_sources, get_source_statistics) is not addressed.

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 its closely-related siblings. There is no mention of when integrity checking is appropriate relative to revalidate_fact_sources (which presumably fixes sources) or get_facts_with_stale_sources (which identifies stale ones). No exclusions or alternatives are named, leaving the agent to guess which of the source-related tools 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 provided, so description carries full burden. It states it checks health and returns a report, but does not disclose if it is read-only, has performance implications, or requires certain permissions.

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 succinct sentences with clear verb and resource; returns section explicitly lists output contents. 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?

Given no output schema, the description adequately explains the return value (total notes, parse errors, recommendations). However, lacks behavioral context like potential cost or read-only nature.

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, and schema coverage is 100% by default. Baseline of 4 is appropriate since description does not need to add parameter details.

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 checks health of all notes and reports parse errors and issues, distinguishing it from sibling check_fact_integrity which focuses on facts.

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 check_fact_integrity or other diagnostic tools. No when-not or context 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?

With no annotations, the description carries the full burden. It discloses auto-generated UUID, return type ('Created note as dict'), and format constraints (tags lowercase/hyphenated, category as path). It does not mention side effects or preconditions, but for a creation tool, this is fairly 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 extremely concise: a one-sentence purpose followed by a structured Args and Returns section. Every sentence adds value, and the front-loaded purpose makes it easy to scan.

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

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

Given no output schema, the description includes return info. It covers creation, parameters, and return type. However, it lacks details on error conditions or idempotency, which would improve completeness for a simple 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 0%, so the description must compensate. It provides clear, helpful descriptions for all four parameters: title, content, tags (with format constraint), and category (with example). This adds significant meaning beyond the schema's type and default information.

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 'Create a new note with auto-generated UUID,' specifying the verb (create), resource (note), and a key behavioral detail (auto-generated UUID). This distinguishes it from sibling tools like update_note, delete_note, and read_note.

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 (e.g., update_note). It only describes the tool's purpose, leaving the agent to infer usage context from the name and siblings.

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 discloses that deletion also removes associated sources, which is important behavioral information. However, it omits details about irreversibility, potential side effects, or any permission requirements, leaving gaps for the 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 extremely concise and front-loaded, with no filler. The essential purpose and parameter are stated immediately, and it remains under a few sentences without unnecessary detail.

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 single-parameter delete operation, the description is mostly sufficient: it identifies the action, input, and output. However, it lacks context on irreversibility, success/error semantics, and any cascading behaviors beyond sources, leaving some ambiguity for 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 description coverage is 0%, so the description must compensate. It adds that fact_id is a UUID string, which clarifies the format beyond the schema's plain string type. Yet it does not elaborate on how the ID is used or any constraints, so only minimal added value.

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

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

The description clearly states the verb 'delete' and the resource 'a fact and its sources', making it distinct from siblings like add_fact and update_fact. It unambiguously conveys the operation's scope.

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

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

The description provides no guidance on when to use this tool versus alternatives such as update_fact, nor any conditions under which deletion is appropriate. It simply states the action without 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 are provided, so the description carries the full burden. It only says 'Delete' and 'Returns: Success status or error,' but does not disclose whether deletion is irreversible, whether it cascades to related data, requires any permissions, or what error behaviors to expect. For a destructive operation this is a significant gap.

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

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

The description is compact and structured with Args and Returns sections. It contains no redundant wording and every sentence contributes useful 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?

With one parameter, no output schema, and no annotations, this description is borderline adequate: it covers the action, the parameter, and a generic return. Missing details like prerequisites, idempotency, and error specifics leave an agent without enough context for robust 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 coverage is 0%, so the description must compensate. It does clarify that term_or_id accepts either a case-insensitive term or a UUID string. However, it doesn't explain how to distinguish a term from a UUID, the expected UUID format, or behavior when multiple entries match. Partial compensation for a single parameter, hence a 3.

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

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

The description uses a specific verb ('Delete') and resource ('glossary entry') and specifies the lookup method ('by term or UUID'). It clearly distinguishes from sibling tools like add_glossary_entry, update_glossary_entry, lookup_term, search_glossary, and list_glossary.

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, no prerequisites, and no exclusions. Unlike get_calls, it does not reference sibling tools like update_glossary_entry or delete_fact to help with selection. The usage context is only implied by the tool name and the verb.

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

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

With no annotations, the description carries the full burden. It discloses the key behavioral traits: the note is removed from the filesystem and search index, but remains recoverable via git history. This gives the agent a clear understanding of the side effects. It does not mention potential error conditions or authentication requirements, but for a simple delete, the core behavior is 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 efficiently structured with a one-line action and effect, followed by a clear Args section and a minimal Returns line. 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 single-parameter delete operation, the description covers the essential context: what is deleted, the effects (filesystem, index, git recovery), and a return status. It does not elaborate on error handling or the exact return format, but given the simplicity and lack of an output schema, the description is reasonably 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?

The schema provides only 'string' with title 'Note Id', and schema description coverage is 0%. The description compensates by specifying that note_id is a 'Note UUID string', clarifying the expected format and meaning. This is valuable guidance 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 action (delete) and the target resource (a note). It also specifies the effect: removed from filesystem and search index, while remaining recoverable from git history. This distinguishes it from other delete tools like delete_fact or delete_glossary_entry.

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 mention of prerequisites, idempotency, or cases where other tools (like update_note or read_note) might be more appropriate. The description simply states what it does.

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 does describe the BFS algorithm and the return shape (list of paths with facts and entities), which is helpful. However, it does not explicitly state that the operation is read-only, nor does it mention performance implications or error behavior (e.g., empty results). It provides some transparency but not comprehensive 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 well-structured with a concise summary first, then an Args section and Returns section. Each sentence earns its place, covering essential details without fluff. It is appropriately sized for a tool with six parameters and effectively front-loads the core purpose.

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 all parameters and the return format, which is sufficient for an agent to invoke the tool correctly. An output schema exists (though not shown), and the description independently explains the output structure. Minor gaps include not specifying what happens when no path is found or error conditions, but for a read-only graph traversal, this is likely acceptable. Overall, it is 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 must fully explain parameters. It does this thoroughly: it lists each parameter, its optionality, defaults, and constraints (e.g., max_depth range 1-10, limit range 1-100). It also clarifies the special behavior of target_entity being optional and what happens when it is None (returns all reachable entities). This completely compensates for the schema's lack of descriptions.

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

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

The description clearly states the tool's function: 'Find connections between entities using BFS graph traversal.' It specifies the verb and resource, and elaborates with 'Discovers how entities are related through chains of facts.' This distinguishes it from most sibling tools that deal with facts, notes, or tags, though it does not explicitly differentiate from the similar 'get_neighbors' tool. 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 lacks any explicit guidance on when to use this tool versus alternatives. It does not mention when to prefer find_connections over get_neighbors or search_facts, nor does it state conditions where it is inappropriate. The reader must infer its use case from the purpose alone, providing no routing to or away from sibling tools.

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

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

No annotations are provided, so the description must disclose behavior. It states 'semantically similar' but does not explain the mechanism, whether the operation is read-only, how results are ordered, or what the returned list contains beyond being similar notes. It also lacks any side-effect or error information. The description is too sparse for an agent to predict outcomes accurately.

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 compact docstring with a one-line purpose, an Args section, and a Returns line. Every sentence is informative and there is no filler. The key purpose is front-loaded, making it easy to scan.

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

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

Given the presence of an output schema (not shown here) and a clear parameter list, the description is minimally sufficient for calling the tool, but it omits important context like whether the note must exist, what happens if no similar notes are found, and how similarity is computed. It also does not distinguish from the many related tools, leaving the agent to guess use cases. Additional detail about the return format or scoring 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 coverage is 0%, so the description carries all parameter semantics. It clarifies that note_id is a UUID string (schema only says string) and specifies limit's default (already in schema) and max value (not in schema). This adds meaningful information beyond the schema, though it could elaborate on edge cases or interpretation of 'limit'.

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

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

The description states a clear verb ('Find') and resource ('notes') with a specific mechanism ('semantically similar'). It distinguishes from list_notes and search_notes by implying semantic rather than lexical matching, though it does not explicitly name alternatives. The purpose is unambiguous and actionable.

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 about when to use this tool instead of its siblings such as search_notes or find_connections. There is no mention of contexts (e.g., need recommendations, clusters) or exclusions (e.g., if a keyword search is intended). The agent must infer usage from the tool name alone.

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 does disclose case-insensitive matching and the optional entity_type filter, and states the return type, but it does not explicitly declare read-only behavior, rate limits, 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 compact and well-structured with Args/Returns sections, front-loading the core action. No redundant or filler wording.

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 lookup, the description provides the essential information needed to call the tool: what it retrieves and what it returns. The return format is only vaguely described as 'Dict with entity info', but it is adequately complete for the tool's simple 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?

The schema provides only titles, so the description compensates by explaining that 'name' is case-insensitive and 'entity_type' is an optional filter. It doesn't enumerate valid entity type values, but the meanings are 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?

States a specific verb and resource: retrieving all facts involving an entity as subject or object. The entity-centric scope clearly distinguishes it from fact-search and neighbor-tool 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?

The description implies the use case (entity-centric fact retrieval) but gives no explicit when-to-use or when-not-to-use guidance. Sibling alternatives like search_facts or get_neighbors are not referenced, so the agent must infer when this tool is the right choice.

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, the description transparently explains the tool's behavior: it returns a list of facts with stale sources or an error if status is invalid. It does not mention destructive or side effects, but the read-only nature is implied.

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 and front-loaded. Every sentence serves a purpose: purpose, usage context, parameter descriptions, and return format. No unnecessary text.

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 required ones) and presence of an output schema, the description provides sufficient detail about parameters and return behavior. It is complete for an agent to use 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?

Adds significant meaning beyond the schema: documents valid values for status ('deleted', 'modified', 'all' default) and limits for limit parameter (default 50, max 100). This compensates for 0% schema coverage.

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

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

Description clearly states the tool's purpose: 'Get facts with stale (deleted or modified) sources.' It uses a specific verb+resource combination and distinguishes from sibling tools like list_facts or search_facts by focusing on stale sources.

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

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

Provides context with 'Useful for identifying facts that may need review or re-verification,' indicating when to use. Lacks explicit when-not-to-use or alternative tools, but the context is sufficient for 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 carries full burden. It discloses the return structure (entity, type, predicate, direction, fact_id) and explains direction semantics (outgoing/incoming). This is adequate for a read-only query tool, though no rate limits or permissions are mentioned.

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 brief summary, then separate Args and Returns sections. Every sentence serves a purpose; no redundant or missing information. Ideal structure for a tool with two parameters.

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 graph query tool with two parameters, the description is complete. It covers purpose, parameters, and return format in detail. The output schema is effectively documented in the Returns section, so no gaps remain.

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 adds meaning beyond the input schema by explaining that entity is the name to look up and entity_type is an optional filter for disambiguation. This fully compensates for any low schema coverage and provides clear 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 clearly states it gets immediate neighbors of an entity in the fact graph, explicitly saying 'all entities directly connected by a single fact'. This is specific and differentiates from sibling tools like find_connections or get_entity.

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 basic usage info (entity required, entity_type optional for disambiguation) but does not guide when to use this tool vs alternatives like find_connections or query_facts. No explicit when-to-use or when-not-to-use 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?

With no annotations, the description carries the full burden. It discloses the use of --follow and the limit default/max, which are behavioral details. However, it does not explicitly state that the operation is read-only or mention any side effects, permission needs, or error behavior. The behavior is partially transparent, but safety aspects are omitted.

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

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

The description is compact and structured, with a clear purpose statement, a behavioral note, and then formatted arguments and returns. No redundancy, and every sentence contributes useful information. It is front-loaded with the core 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 tool is simple, and the description covers the purpose, arguments, and returns at a high level. Given that an output schema exists, not detailing the return format is acceptable. It could mention read-only nature or error conditions, but for a basic retrieval tool, it is largely complete. A 4 reflects that it is sufficient but not exhaustive.

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 adds significant value beyond the schema: it specifies that note_id is a UUID string and that limit has a max of 100 (the schema only shows a default of 10). Both parameters are clearly explained, and since the schema description coverage is 0%, this is essential and well done.

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 it gets version history for a note from git, and specifies the use of --follow to track file moves/renames. It distinguishes itself from the sibling restore_note_version (which restores) and other related tools by identifying the specific action (retrieve history) and resource (note).

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: when you need version history of a note. It does not explicitly compare to alternatives or state when not to use it, but the context is clear. There is no mention of exclusions, but the tool's purpose is self-evident, so a 4 is 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 carries the burden. It discloses the return value structure (outgoing, incoming, broken links), but does not mention side effects, permissions, or constraints. Minimal but not misleading.

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?

Extremely concise: one sentence for purpose, one line for args, one line for returns. No unnecessary words, well-structured, and front-loaded.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, parameter format, and return structure adequately. Missing definitions of 'broken links' or edge cases, but still generally 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?

The schema has 0% description coverage. The description specifies note_id as 'Note UUID string', adding format detail beyond the schema's string type. However, it does not elaborate further on expected 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 starts with 'Get incoming and outgoing links for a note,' clearly stating the action and resource. It distinguishes from siblings like 'find_connections' and other note tools by focusing specifically on links.

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, such as 'find_connections' or 'read_note'. No prerequisites or context for usage are 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does state the return format ('Dict with source counts by status and integrity score') and the scope ('across all facts'), but it doesn't explicitly confirm the operation is read-only (though 'Get' implies it) nor mention any side effects, performance implications, or access requirements. The return description adds some transparency but lacks depth.

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

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

The description is succinct and well-structured, with a clear opening line and a dedicated 'Returns' section that outlines the output. It avoids fluff and stays focused on the essential information. The only minor issue is the slight redundancy between the second line and the 'Returns' block, but overall it is 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?

For a zero-parameter tool with no output schema, the description covers the main purpose and return shape, but it leaves ambiguities: it doesn't define what 'status' means (e.g., possible statuses like 'verified', 'stale'), nor does it explain the integrity score's range or interpretation. An agent might need that context to interpret the returned dictionary properly. The description 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?

The tool has zero parameters, so the baseline is 4. The description appropriately acknowledges the absence of parameters by focusing on what is computed globally. Since there are no parameters to document, this dimension is effectively satisfied.

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: 'Get statistics about fact source integrity' and specifies the output as counts of sources by status and an integrity score. It distinguishes itself from sibling tools by focusing on aggregate statistics rather than individual integrity checks (check_fact_integrity) or listing stale sources (get_facts_with_stale_sources), though it doesn't explicitly name alternatives. Overall, 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 provides no guidance on when to use this tool versus the related integrity tools. It doesn't state any prerequisites, context, or exclusions. For a statistics-gathering tool, one might expect guidance like 'Use this to get an overview of source health, while check_fact_integrity is for per-fact verification.' This omission leaves the agent to infer usage from the name alone.

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 the full burden. It explains the effect of the force parameter and mentions the return type ('indexing result with counts'), providing useful behavioral context. However, it does not disclose side effects like whether indexing is asynchronous or whether it overwrites existing indexes, though force implies reindexing.

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 plus the parameter definition—extremely efficient. The main action and purpose are front-loaded, and the parameter explanation is clear and 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?

For a simple single-parameter tool with no output schema, the description covers the operation, parameter semantics, and return value. It could mention prerequisites or dependencies, and it doesn't explicitly disambiguate from reindex_notes, but the tool name itself provides that distinction. Overall, sufficient for an agent to invoke 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 schema has 0% description coverage, so the description must explain the parameter. It fully does: 'force: If True, reindex all facts. If False, only index new facts.' This goes beyond the schema's bare boolean type and default.

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?

Clear verb ('Index') and resource ('all facts') with explicit purpose ('for semantic search'). The name and description clearly distinguish this from siblings like reindex_notes (notes vs facts) and search_facts (search vs index).

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 such as reindex_notes or search_facts. It doesn't state conditions for use or exclusions, leaving the agent to infer from 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, and the description only mentions output is a 'Category tree' without details on behavior like result limits, ordering, or authorization requirements. It lacks 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 extremely concise with two sentences, no wasted words, and the purpose is front-loaded.

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

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

For a zero-parameter list tool, the description is adequate but lacks details about the structure of the 'Category tree' or any limits. It could be improved by specifying what the tree contains.

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 to describe, and schema coverage is 100%. The description confirms the tool takes no input filters, which adds meaning beyond the 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 the tool lists all categories with note counts and hierarchy, distinguishing it from sibling tools like list_tags and list_notes.

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 (to list categories) but provides no guidance on when not to use it or alternatives. No exclusions or context are given.

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

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

With no annotations, the description must carry the behavioral burden. It states the return is a list of fact summaries and includes parameter explanations, but it does not explicitly state that the operation is read-only, mention any side effects, or disclose limitations like pagination behavior or whether summaries omit certain fields. The phrase 'lightweight summaries' implies limited detail, which is helpful, but the absence of explicit safety or scope notes leaves some ambiguity.

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

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

The description is compact and well-organized with a clear Args/Returns structure. Every sentence contributes to functionality. It is slightly terse — for instance, it could mention sorting or result ordering — but it remains efficient and easy to parse, achieving good conciseness without unnecessary 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 the presence of an output schema (not shown here but indicated), the description need not elaborate on return structure, but it could offer more context around the tool's position among siblings. It explains the filtering parameters but omits any note on default ordering, whether results are sorted, or if there are any restrictions on combining filters. For a simple list tool with four parameters, the level of completeness is adequate but not exceptional.

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 adds meaning beyond the input schema by explaining each parameter in the Args section: limit (with a range and default), subject_type, object_type, and predicate as filters. The schema only provides titles and types, so the description fills a critical gap, especially providing the limit constraint (1-100) not present in the schema. This is substantial added value.

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

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

The description clearly states the tool 'List facts as lightweight summaries.' It identifies the verb (list) and resource (facts) and adds the qualifier 'lightweight summaries' to indicate a summarized representation. This helps distinguish it from tools like query_facts or search_facts, but does not explicitly name alternatives or contrast levels of detail.

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 its many siblings (query_facts, search_facts, list_tags, etc.). It lacks any mention of alternatives, prerequisites, or scenarios where this tool is preferred. An agent is left to infer the appropriate context from the name and generic 'list' 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 carries the full burden of behavioral disclosure. It mentions the return format but does not explicitly state that this is a read-only operation, nor does it clarify pagination behavior. The phrase 'List all' is potentially misleading given the default limit of 50, which is a behavioral trait that should be disclosed. No information about sorting, exactness of domain filtering, or access requirements is 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 concise and well-structured: a one-sentence purpose, labeled Args, and a Returns line. Every sentence adds value, with no redundant content. The format is easy to scan and front-loads the primary purpose.

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 return value description is sufficient. Both parameters are covered semantically, and the tool is simple enough that nothing critical is missing for basic invocation. The main gaps are the unaddressed tension between 'List all' and the default limit, and the lack of usage alternatives among siblings, which prevents a perfect score.

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 fully compensates by explaining both parameters. 'domain: Optional domain filter' gives functional meaning beyond the schema's type/default, and 'limit: Max results (default 50, max 100)' clearly defines the constraint and bounds. This is exactly the semantic information an agent needs to set these parameters correctly.

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 and resource: 'List all glossary entries with optional domain filter.' It clearly identifies the operation as a read-only listing of glossary entries. It does not explicitly differentiate from sibling tools like search_glossary or lookup_term, but the 'all' scope provides some implicit distinction.

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 by stating the tool lists entries with an optional domain filter, but it provides no explicit when-to-use guidance or mention of alternatives. With siblings like search_glossary and lookup_term present, an agent would benefit from selection criteria, but none are given. The guidance is minimal and left to inference.

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

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

With no annotations, the description carries the full burden. It discloses that invalid sort_by returns an error dict, and that tags must all match. However, it does not mention pagination behavior, the structure of note summaries, or that it is a read-only operation. Adequate but incomplete behavioral disclosure.

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, front-loaded with the main purpose, and uses a clear Args/Returns structure. Every sentence adds value. Slightly verbose in the Args list but appropriately formatted.

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 (4 optional parameters) and presence of an output schema, the description covers the essential input semantics and the error case. It lacks guidance on when to prefer this over search_notes, but that falls under usage guidelines. Overall sufficient for correct invocation.

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

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

Schema description coverage is 0%, so the description fully compensates by explaining each parameter: tags (all must match), category (prefix), sort_by (allowed values and default), limit (default and max). This adds meaning far beyond the schema's bare property names and defaults.

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 'List notes with optional filtering,' which identifies the verb (list) and resource (notes). It distinguishes itself from read_note (single note) and search_notes (full-text search) but does not explicitly name alternatives, so it's clear but not differentiated.

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?

There is no guidance on when to use this tool versus search_notes or list_tags/list_categories. The description focuses on parameters but does not explain the selection criteria (e.g., when to filter by tags vs. search). This leaves the agent to infer 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?

The description states it returns a list of tag info with note counts, which implies a read-only operation. However, with no annotations provided, it does not disclose any behavioral traits like potential ordering, pagination, or performance characteristics. It is minimally adequate but lacks detail for a full behavioral understanding.

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 at two lines plus a return line, with no wasted words. It immediately states the action and result, making it efficient for quick parsing by 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?

Given no parameters, no annotations, and the presence of an output schema (though not shown here), the description sufficiently covers the tool's purpose and output. It does not omit any critical information for a simple listing operation, though it could hint at whether the list is sorted or limited.

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

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

The input schema has zero parameters, so there is nothing to explain. Schema coverage is 100%. The description adds value by stating the output includes note counts, which is not in the schema (which is empty). This meets the high baseline for zero-parameter tools.

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', the resource 'all tags', and the included data 'with note counts'. This distinguishes it from sibling tools like list_categories (categories vs tags) and list_notes (notes vs tags). The purpose is specific and actionable.

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 its many siblings, such as list_categories or list_notes. There is no mention of prerequisites, exclusions, or alternative tools, leaving the agent to infer context from the tool name alone.

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

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

With no annotations provided, the description carries the full burden. It discloses that lookups are case-insensitive and returns either a glossary entry or an error dict. It does not explicitly state that it performs no side effects, but that is reasonable for a lookup tool. The behavior is largely transparent, but could mention read-only intent.

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

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

The description is compact and well-structured: a single purpose line, followed by Args and Returns sections. There is no fluff, and every sentence serves a purpose. The most critical information (exact, case-insensitive) is front-loaded.

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

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

For a simple one-parameter lookup tool, the description covers the essential details: what it does, parameter examples, and return type. It lacks a precise definition of the glossary entry structure, but no output schema exists. The description is sufficient for an agent to know when and how to call it, though it could be more explicit about the return format.

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

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

The schema provides only the parameter name 'term' without any description (0% coverage). The description compensates excellently by explaining the parameter's meaning and offering concrete examples ('usaf', 'USAF', 'US Air Force'), and noting aliases are accepted. This 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 action (exact lookup), the resource (term or alias), and the case-insensitivity. However, it does not explicitly differentiate from sibling tool 'search_glossary' which likely supports fuzzy/partial matching. The term 'exact' implies a distinction, but it's not named.

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

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

The description implies usage: if you have an exact term or alias, use this tool; otherwise, use search_glossary. However, it does not explicitly mention alternatives or when not to use this tool. The context of 'exact lookup' suggests a dichotomy, but the guidance is implied rather than stated.

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 it returns a count of notes updated or an error dict, which is useful. However, it does not explain what happens to the source tags after merging (e.g., are they deleted?) or any prerequisites (e.g., tags must exist).

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 no unnecessary words. The Args section is somewhat redundant with the schema, but it provides a quick reference. It front-loads the main purpose effectively.

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 output schema, and no annotations, the description is moderately complete. It explains the return value but lacks details on validation failures, edge cases (e.g., empty source_tags), and the merging effect on notes.

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. The Args section briefly explains 'source_tags' and 'target_tag' but lacks details like allowed formats, whether tags must already exist, or behavior when tags are the same.

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 merges multiple tags into one, which is a distinct operation from siblings like rename_tag (renames a single tag) or delete_tag (deletes a tag). The verb 'merge' and the resource 'tags' are specific.

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 (e.g., rename_tag or delete_tag). The purpose is implied but no exclusions or context are 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 full burden. It discloses the return type ('Count of notes updated'), indicating a mutation. However, it does not detail effects on existing notes, required permissions, or behavior if old_path does not exist.

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 no wasted words. The first line states the purpose, followed by structured parameter descriptions and return value. It is well-organized and 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's simplicity (2 parameters, no output schema), the description covers purpose, parameters, and return value. It lacks error conditions and details about category hierarchy behavior, but is largely 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 description coverage is 0%, so the description adds meaning beyond the schema. It explains parameters: 'old_path: Current category path, new_path: New category path'. This adds value but lacks format or constraint details.

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 'Move/rename a category' using a specific verb and resource. It distinguishes from sibling tools like rename_tag (which renames a tag) and merge_tags (different 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 explicit guidance on when to use this tool versus alternatives like rename_tag or merge_tags. The context implies its use for category path changes, but no when-not or prerequisites are mentioned.

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 must carry the burden. It implies a read-only action via 'Query' and states a return type, but does not explicitly confirm non-mutation, explain filter combination semantics, or disclose potential side effects or limitations. This is a significant gap for a tool with 8 optional filters.

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 short and front-loaded with the main purpose. The Args block duplicates the schema property list, but the added notes are useful. It is not overly verbose, though it could be tightened by merging parameter details into a more 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?

Given 8 optional parameters and no output schema specification in the description, the tool lacks essential context: how filters combine (AND/OR), matching semantics (exact vs partial), pagination behavior, or a typical use case. The description is too thin for an agent to confidently construct complex queries, especially without any annotation support.

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

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

The Args block provides meaning beyond the schema: it clarifies case-insensitivity for subject/predicate/object, the ISO format for valid_at, a threshold meaning for min_confidence, and a range for limit. Since the schema has no descriptions (coverage 0%), this compensation is valuable, though explanations are brief and some are just restatements of the 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 the tool queries facts with criteria, which is a clear verb and resource. However, it doesn't differentiate from sibling tools like search_facts or list_facts, and 'various criteria' is vague without context. It's more specific than a tautology but lacks explicit differentiation.

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?

There is no guidance on when to use this tool versus alternatives like search_facts or list_facts. The description provides no context for selecting this filter-based query over other fact-access tools, leaving the agent to infer its place among siblings.

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 only says 'Read' and 'Returns: Note as dict,' which implies a read-only operation, but it does not disclose error behavior, what happens for invalid/missing UUIDs, or any side effects. For a tool with zero annotation coverage, more behavioral context 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?

The description is compact and well-structured with Args and Returns sections. Every sentence contributes necessary information, and the core purpose is front-loaded. No unnecessary detail or repetition.

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

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

For a simple one-parameter read operation, the description covers the essential purpose and parameter semantics. However, with no output schema, 'Note as dict' is vague about what fields will be returned, and error behavior is not mentioned. It is adequate 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 coverage is 0%, and the schema only says note_id is a string. The description adds meaningful semantics by identifying it as a 'Note UUID string,' clarifying both the format and the semantic role of the parameter. This largely compensates for the sparse 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?

States a clear, specific operation: 'Read a note by its UUID.' This directly identifies the resource and retrieval mechanism, and distinguishes it from search/list/create/update/delete siblings. The purpose is immediately understandable.

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?

Usage is implied by the UUID parameter: you should call this when you already have a note's UUID and need the full note. However, there is no explicit guidance about when to prefer read_note over search_notes, list_notes, or get_note_history, and no exclusions are stated.

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 the burden. It reveals action ('Force reindex') and return ('Index status'), but lacks details on performance impact, safety, or permissions.

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 concise sentences. Front-loaded purpose, no wasted words. Perfectly sized for the tool's simplicity.

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

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

Adequate for a zero-parameter tool with simple output. Covers purpose and return value. Could mention idempotency or side effects, but not essential given the tool's minimal scope.

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). Description adds no parameter info, but none needed. Baseline score 4 for zero-parameter tools.

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 verb 'reindex', resource 'all notes', and context 'after manual file edits'. Distinct from sibling tools like create_note or search_notes.

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

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

Explicitly states when to use ('after manual file edits'). Does not mention when not to use, but context is sufficient for a simple maintenance tool.

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

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

With no annotations, the description must fully disclose behavior. It mentions the action and return value ('Count of notes updated, or error dict if validation fails'), but it omits important behavioral details such as what happens if the new tag already exists (merge, overwrite, or error), whether the operation is reversible, or if it affects archived notes. These gaps significantly 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 and well-structured with an Args and Returns section. Each sentence earns its place, and there is no fluff. The format is easy to parse and directly usable.

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 mutation tool with no annotations and no output schema, the description lacks critical context: it does not specify behavior when the new tag exists, whether it renames in all note types, or any side effects. The sibling merge_tags exists but the description doesn't clarify the distinction, leaving the agent to guess.

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 provides brief explanations: ' to rename' and 'New tag name,' which add minimal meaning beyond the schema titles. However, it doesn't clarify formatting, validation rules, or edge cases like empty strings or tag collisions, so compensation is only partial.

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

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

The description states a clear action: 'Rename a tag across all notes.' This identifies the verb and resource specifically, and the scope ('across all notes') adds clarity. It is distinguishable from sibling merge_tags by the rename versus merge operation, though it doesn't explicitly contrast them, so it misses full differentiation.

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 merge_tags. The description only states what it does, not the context or prerequisites. There is no mention of when not to use it or which scenarios favor this tool over a sibling.

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. It discloses a key behavioral trait—that the restore creates a new commit—which implies the operation is non-destructive to existing history. However, it does not mention side effects, permission requirements, or potential errors, though the commit detail adds valuable transparency beyond the basic mutation.

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 clear one-line purpose followed by parameter definitions and a return note. No fluff; every component serves a purpose. The structure is front-loaded with the core 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 tool is simple with two parameters and no output schema. The description covers the purpose and parameters but lacks details on the return value's format, prerequisites, error conditions, and side effects beyond the commit creation. While adequate for a basic call, it could be richer given the absence of annotations and output schema.

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 clearly explains note_id as a 'Note UUID string' and version_id as a 'Git commit SHA to restore from', providing format and semantic meaning that the schema lacks. It doesn't include examples or constraints but is sufficient for both 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 states a specific verb ('Restore') and resource ('note') with a clarifying parenthetical ('creates new commit') that distinguishes it from other note operations like update_note or get_note_history. 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 implies when to use the tool (when restoring a note to a previous version) but does not explicitly mention alternatives or exclusions. It also does not provide guidance on how to obtain the version_id (e.g., from get_note_history), leaving usage as implied rather than explicit.

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 fully discloses behavior: resets status, returns count, accepts optional filters. It does not mention side effects or permissions, but the mutation is reversible (reset to active).

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 three short paragraphs. The main purpose is front-loaded, and every sentence adds value. No 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?

Given the tool has two optional parameters and no output schema, the description explains return value ('Count of sources revalidated'). It covers purpose, usage, and parameters well. Could mention if limits apply, but overall 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 coverage is 0%, but the description's 'Args:' section adds meaning: explains source_id as optional UUID for a note/glossary entry, and source_type as optional filter with examples ('note', 'glossary', 'document'). This goes 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 resets modified/deleted sources back to active after re-verification. It uses a specific verb and resource, and distinguishes from sibling tools like get_facts_with_stale_sources.

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

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

The description explicitly says 'Use this after manually verifying that sources are still valid,' providing clear context and when to use. It does not mention when not to use or alternatives, but for this tool, no alternatives are needed.

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

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

No annotations are provided, so the description must carry the behavioral burden. It does disclose that it performs semantic search and returns a list with scores, and it clarifies the limit range. However, it does not explicitly state that the operation is read-only (though implied), nor does it mention any special behaviors like partial matches, staleness handling, or performance considerations. It is sufficient for a simple search but not rich.

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

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

The description is compact and well-structured: a one-line purpose, then Args/Returns sections. Every sentence contributes value, and the most important information (purpose) is front-loaded. No redundancy 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?

Given that there is an output schema (indicated by the context signal) and only two simple parameters, the description is adequate. It explains the input, the return behavior, and the limit semantics. It does not mention error scenarios or edge cases, but those are often not required for a basic search. It is complete enough for an agent to make a correct call.

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

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

The schema only provides types and a default, but the description adds meaningful semantics: 'query' is described as a 'Natural language search query' and 'limit' as 'Maximum results (1-100, default 10)'. This gives an agent the exact range and an understanding of what the parameters are used for, fully compensating for zero 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 a specific action ('Semantic search') on a specific resource ('indexed facts'). This distinguishes it from sibling tools like 'query_facts' or 'search_notes' by emphasizing semantic (natural language) retrieval. It also describes the return format, so an agent knows what to expect.

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 natural-language fact searches but does not explicitly contrast it with alternatives such as 'query_facts' or 'list_facts'. There is no 'when to use' or 'when not to use' guidance. This leaves the agent to infer the right tool among many siblings, which is a missed opportunity.

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

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

Annotations are absent, so the description carries the full burden. It does disclose the return shape ('List of matching entries with relevance scores, or error dict'), but it does not state read-only behavior, result ordering, empty-result handling, or any operational caveats.

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

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

The description is compact and well-structured: a one-line purpose, an Args block, and a Returns block. Every sentence contributes meaningful information 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?

Given the output schema exists and the tool only has three parameters, the description covers essential invocation details. It could be more complete by explaining when to choose this over lookup_term, but nothing critical is missing for making a basic call.

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%, but the description compensates by defining query as a natural-language search, domain as an optional filter, and limit as max results with defaults and maximum. It adds practical meaning to all parameters, though domain values remain unspecified.

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

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

The description opens with a specific action and resource: 'Semantic search for glossary entries.' It clearly states what the tool does, though it does not explicitly differentiate itself from sibling tools like lookup_term or list_glossary.

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?

There is no guidance on when to use semantic search versus lookup_term or list_glossary, and no mention of alternatives or exclusions. The natural-language query intent is implied but never framed as a usage rule.

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 discloses the hybrid semantic + keyword nature, supported filters, limit default/max, and that it returns a list of results. It does not clarify how query-string filters interact with the dedicated parameters, result ordering, or whether the operation is strictly read-only, though search strongly implies it.

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-organized, starting with a one-line purpose and then using compact bullet lists for query syntax, arguments, and return value. There is some redundancy between the query-syntax filters and the args list, but the structure is scannable and front-loaded without 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 the sparse schema and lack of annotations, this description provides enough invocation detail: the required query, optional filters, limit behavior, date formats, and return type. The presence of an output schema reduces the need for a detailed return description. Minor gaps remain around sibling differentiation and filter combination semantics, but the agent can call the tool correctly from this description alone.

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

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

Schema description coverage is 0%, so the description must compensate for the bare schema. It adds meaningful semantics: query expects search text with optional filter syntax like tag:tagname and title:text, limit has default 10 and max 100, dates are ISO format, and tags/category are additional filters. This goes well beyond the schema field names, though it could be clearer about array behavior for tags and how args combine with query-string filters.

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 opening line 'Hybrid semantic + keyword search across all notes' clearly states the verb, resource, and scope. It is recognizable as a search/retrieval operation, but it does not explicitly differentiate itself from sibling search tools like search_facts or find_similar_notes.

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 the tool: whenever a user wants to search notes by semantic or keyword matching, with optional filtering. However, it provides no explicit guidance about when to prefer this tool over alternatives such as list_notes, read_note, or find_similar_notes, nor 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?

With no annotations, the description carries the behavioral disclosure burden. It explains null-vs-empty-string semantics for context, valid_from, and valid_to, and notes the immutability constraints. It does not cover failure behavior (e.g., missing fact_id) or confidence null semantics, but the provided context is strong.

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-organized with a clear one-line purpose, a useful immutability note, structured Args, and Returns. Every sentence adds value and there is no redundancy 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?

Given five parameters and no output schema, the description covers the purpose, all parameters, return type, and key behavioral nuances. Missing details include confidence null handling and error cases, but the tool remains safely invocable as documented.

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 fully explain parameters. It does so well for fact_id, context, valid_from, and valid_to, including null/empty behavior. Confidence gets a range note but lacks the equivalent null-means-unchanged clarification, leaving a minor 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 operation: "Update an existing fact's metadata." It specifies the resource (facts) and the scope (metadata only), and the immutability note distinguishes it from add_fact and delete_fact 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?

The description explicitly tells the agent that subject, predicate, and object cannot be changed and that those require delete and recreate. This gives clear when-to-use and when-not-to-use guidance relative to sibling tools.

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

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

With no annotations, the description bears the full burden and does well: it discloses that the operation is an update, explains partial-update semantics, and specifies how to clear domain (pass "" or null) and aliases (pass []). It also states the return value as the updated entry dict.

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 a clear one-sentence purpose and the critical 'only provided fields are updated' caveat. The Args/Returns format is efficient, with no redundant or irrelevant text.

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 core operation, parameters, clearing semantics, and return type. It lacks details on error conditions or permission requirements, but for a straightforward glossary update these are not essential, making it nearly 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%, but the description compensates thoroughly by explaining each of the 6 parameters, including the special clear behavior for domain and aliases and the role of term_or_id for identification. This adds significant semantic meaning beyond the bare 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?

The description clearly states the tool updates an existing glossary entry and explicitly notes that only provided fields are updated. This distinguishes it from sibling tools like add_glossary_entry (creation) and delete_glossary_entry (removal), though it does not name a specific alternative.

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 implicitly signals usage when an entry already exists and needs modification, and the 'Only provided fields are updated' note is a key guideline. However, it does not explicitly state when to prefer this over other glossary tools, nor does it mention any exclusions or 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 carries the full behavioral burden. It discloses important side effects: title may trigger file rename, category may trigger file move, empty tags/category clear those fields, and the return value is the updated note. This is strong coverage for a simple 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 concise and well-structured: a one-sentence summary, an Args list, and a Returns line. Every sentence adds useful information with no repetition or fluff.

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

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

The description adequately explains parameters, behavioral side effects, and return type. The only minor gap is that 'Updated note as dict' does not enumerate the dict's fields, but this is acceptable given the note's schema is likely shared and no output schema was provided.

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%, but the Args section fully compensates by explaining each parameter's meaning and special behavior: note_id is a UUID, title may rename the file, tags accepts an empty list to clear, and category accepts an empty string to clear. This adds substantial meaning beyond the raw 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?

States a specific verb and resource: 'Update an existing note.' The phrase 'Only provided fields are updated' clarifies the partial-update semantics, which distinguishes it from create_note, delete_note, and full-overwrite 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?

Description clearly establishes the operation context: modifying an existing note by providing optional fields. It does not explicitly name alternatives or exclusion conditions, but the sibling context makes the intended use unambiguous.

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