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

No annotations are provided, so the description bears full responsibility. It discloses batch processing and the optional index building, but omits details like error handling, performance impact, or whether the operation is reversible.

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?

Three concise sentences, each providing unique information: purpose, batching, and the build_index option. No unnecessary words.

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

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

Despite an output schema existing, the description does not mention what the tool returns (e.g., count of rows affected, success status). This is a significant gap. Also, batching mechanics (e.g., order, progress feedback) are vague.

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

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

Schema description coverage is 0%, yet the description only explains build_index. batch_size, limit, and dry_run are not elaborated, leaving the agent to infer their purpose from names alone. This is insufficient for a tool with 4 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?

Description clearly states the specific action: backfilling the query_embedding column in retrieval_telemetry for rows predating Phase 4a. This distinguishes it from sibling tools like kb_backfill_embeddings.

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 mentions batching and the build_index option for index creation. While not explicitly stating when not to use, the context (retroactive backfill) is clear. No alternatives are named, but the sibling context provides differentiation.

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

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

The description discloses that the cluster count is data-driven, not parameter-controlled, and references the removal of misleading knobs (Issue #22). This provides useful behavioral context beyond the name. No annotations exist to supplement, so this is relatively 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?

Two sentences, each earning its place. The first sentence states the core purpose, the second adds behavioral nuance. No redundancy or fluff.

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

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

An output schema exists, so return values need not be described. However, the absence of parameter documentation and usage context (e.g., what constitutes valid input) leaves gaps. Completeness is adequate for a simple tool but could be improved.

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

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

The single parameter 'results' is an array of objects with no schema description (0% coverage). The description does not explain the expected structure or required fields of input objects, leaving the agent to infer from context. The description adds minimal value over 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 ('Groups search results') and specifies the grouping criteria ('by source_type (file extension, corpus, transcript)'). This distinguishes it from sibling tools like 'deduplicate_results' or 'search_corpora'.

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

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

The description implies the tool is for grouping by source type but provides no explicit guidance on when to use it versus alternatives like 'deduplicate_results' or 'search_corpora'. No exclusions 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?

No annotations are provided, so the description carries full burden. It only states the basic functionality but does not disclose side effects, whether the input array is modified, or what the return value looks like. The output schema exists but is not leveraged.

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

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

The description is one sentence, which is concise but arguably too brief. It front-loads the purpose but lacks necessary detail, making it minimally viable but not well rounded.

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 absence of annotations and low schema coverage, the description is incomplete. It does not explain the output schema, how the tool handles edge cases (empty results, threshold 0 or 1), or its relation to sibling tools like cluster_results or search_corpora.

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

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

Schema description coverage is 0%, and the description adds no meaning beyond the schema. It does not explain what 'threshold' represents (e.g., similarity threshold) or how 'results' should be structured. The parameter 'threshold' has a default but no explanation, leaving the agent uninformed.

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

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

The description clearly states the action ('Remove duplicate'), the resource ('search results'), and the method ('based on text similarity'), distinguishing it from the sibling cluster_results which groups results.

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

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

No guidance on when to use this tool vs alternatives, no prerequisites or exclusions provided. The description is too minimal to help an agent decide when to invoke deduplicate_results.

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 full burden. It discloses that the tool is a read operation, specifies the source table, and mentions sorting. However, it does not address safety, permissions, idempotency, or potential side effects.

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

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

The description is concise, using two short sentences to convey the tool's action, filters, and sorting. No redundant information is present.

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

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

The description covers the main functionality and filters but does not mention the default limit (100) or pagination behavior. Since an output schema exists, return values are not needed, but the lack of limit clarification is a minor gap.

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

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

Schema description coverage is 0%, so the description adds needed meaning. It explains that signal_type accepts values like 'explicit/behavioral/all', and that doc_id and query_text_like are filter names. However, it omits description of the 'limit' parameter and does not fully detail all parameter formats.

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 (read), the resource (hard negative pairs from knowledge.hard_negative_pairs), and the key filters (signal_type, doc_id, query_text_like). It also mentions sorting, making the tool's purpose unambiguous and distinct from sibling tools like refresh_hard_negatives.

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

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

The description does not provide any guidance on when to use this tool versus alternatives, such as when to use refresh_hard_negatives instead. No explicit when-to-use or when-not-to-use information is given.

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

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

Discloses read-only nature, selector precedence, and sorting order (newest-first). With no annotations, it carries the burden well but lacks details on pagination or authentication.

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-load key information, though the 'issue #5' reference is extraneous.

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?

Provides ordering and precedence but omits description of each parameter's meaning and does not clarify the 'recent' fallback. Adequate but has 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?

Adds value by explaining selector precedence and hinting at limit, but does not individually describe query_id, session_id, or topic; 0% schema coverage demands more detail.

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

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

Description clearly states verb 'Read' and resource 'retrieval telemetry rows', and differentiates from siblings like get_telemetry_stats by mentioning selector precedence.

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 explicit selector precedence, guiding selection among optional parameters, but does not explicitly state when to use versus alternatives.

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

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

No annotations provided, so the description carries full burden. It discloses the aggregate behavior and optionally scoping, but does not mention side effects, performance, or read-only status. Basic transparency, but could add more 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?

Two sentences, each delivering distinct, relevant information: first sentence lists the returned stats, second sentence explains optional filtering. No redundancy or fluff.

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

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

The description lists all key output fields and parameter purpose, which is sufficient given the output schema exists. The tool is simple (2 optional params, no required params) and the description covers the main functionality. Minor omission: not explicitly stating it's read-only, but implied.

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 states parameters are for scoping ('Optionally scoped by session_id and/or topic'), adding meaning beyond the schema. However, it lacks details on expected formats or constraints, only partially compensating for low coverage.

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

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

The description clearly states the verb 'aggregate' and the resource 'retrieval telemetry stats', listing specific computed fields. It does not explicitly differentiate from sibling 'get_retrieval_telemetry', but the name and content suggest it's an aggregate variant.

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 mentions optional scoping by session_id and/or topic, implying when to filter. However, it lacks explicit guidance on when to use this tool versus alternatives like get_retrieval_telemetry, and no when-not-to-use information.

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

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

No annotations are provided, so the description must disclose behavioral traits. It only says 'add an investigation entry (open or append)' without explaining what 'open' vs 'append' entails, whether it modifies existing data, or any side effects. Missing critical transparency for a mutation tool.

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

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

The description is one sentence, which is concise but overly terse. It lacks necessary detail about modes and parameters, making it incomplete rather than efficiently written.

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 0% schema descriptions and no annotations, the description is insufficient for a tool with 4 parameters and an output schema. It does not explain the two modes, return values, or how inputs relate to behavior, leaving significant gaps.

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

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

Schema description coverage is 0%, but the description does not elaborate on the parameters (topic, title, content, tags). It only vaguely refers to 'investigation entry', failing to add meaning beyond 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 clearly states the verb 'add' and the resource 'investigation entry', and specifies two modes ('open or append'). It is distinct from sibling tools like investigation_list or investigation_delete_note, though it could clarify what 'ops investigation' means.

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 (e.g., journal_append, kb_add). It does not mention when not to use it or any prerequisites, leaving the agent to infer usage context.

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

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

The term 'hard-delete' implies permanent destruction, and the confirmation flags are specified. However, with no annotations, the description does not disclose side effects, error conditions, or return behavior, leaving some gaps.

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 tightly written sentences, front-loading the action and adding crucial prerequisites. No filler or redundancy.

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

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

For a simple delete tool with an output schema (not shown), the description covers the main purpose and confirmation requirements. Minor omission: behavior if confirm is false, but overall sufficient.

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

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

Despite 0% schema coverage, the description adds critical context: experiment_id is the identifier, confirm must be true (overriding default), and confirm_production is required in production. This 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 hard-deletes an investigation experiment by experiment_id. It distinguishes from siblings as the only delete experiment tool, with no ambiguity.

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

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

The description explicitly requires confirm=True and, in production, confirm_production=True, guiding when and how to use. It does not mention alternatives or when not to use, but the context is clear enough.

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

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

Discloses destructive action (hard-delete) and confirmation requirements. With no annotations, it covers key behavioral traits, though could detail side effects or reversibility.

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, zero waste. Front-loads purpose, then adds critical constraints. Every part earns its place.

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

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

Sufficient for a delete operation; output schema exists so return values are covered. Could note how to obtain note_id, but siblings like investigation_list provide that context.

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

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

Description adds meaning beyond schema by specifying that confirm=True is required and that confirm_production is needed in production. Note_id is not elaborated, but the confirmation parameters are effectively explained.

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 'hard-delete an investigation note by note_id', specifying action and target. Distinguishes from sibling tools like investigation_add and investigation_delete_experiment.

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 the requirement for confirm=True and confirm_production=True in production. Provides clear conditions for use but lacks alternatives 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?

No annotations are provided, so the description must disclose behavior. It states 'Get' implying read-only, but does not mention error handling, idempotency, or what happens if the ID does not exist. The presence of an output schema reduces the need to describe return format, but behavioral gaps remain.

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

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

The description is a single concise sentence (6 words), efficiently conveying the core purpose. It is appropriately sized for a simple get-by-id tool, though it sacrifices parameter elaboration.

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 (1 required parameter, output schema exists), the description is minimally adequate. It covers the essential action and resource, but lacks details on error conditions or prerequisites.

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 says 'by ID', which adds minimal value since the parameter name 'note_id' already suggests it is the ID. No format, example, or constraints are given.

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 'Get a single investigation entry by ID' clearly states the verb (Get), resource (investigation entry), and the method (by ID). This effectively distinguishes it from sibling tools like investigation_list (list all) and investigation_add (create).

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 have a specific ID and want a single entry, differentiating it from investigation_list (likely returns multiple) or investigation_add (creates). However, no explicit when-not or alternative scenarios 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?

No annotations are provided, so the description must disclose behavior. It fails to mention output format, pagination, filtering, or any constraints. The presence of an output schema is not acknowledged.

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 but at the cost of being under-specified. Effective conciseness requires conveying necessary information efficiently, which is absent here.

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 zero annotations, one optional parameter, and many sibling tools, the description is completely inadequate. It does not address any of the agent's likely uncertainties.

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

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

Schema description coverage is 0% and the description does not mention the 'topic' parameter. No added value beyond the schema structure.

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

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

Description is 'List investigations', a tautology of the tool name 'investigation_list'. It does not provide any additional context or differentiation from sibling tools like investigation_list_experiments.

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

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

No guidance on when to use this tool versus alternatives (e.g., investigation_list_experiments, investigation_get). The description offers no context for decision-making.

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 states the action without disclosing behavioral traits such as whether it is read-only, requires authentication, or handles empty results.

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

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

The description is a single sentence that is concise and front-loaded. Every word is necessary and contributes to conveying the tool's 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 tool has an output schema, so return values do not need description. However, the minimal description lacks behavioral context. It is adequate for a simple list operation but could be improved by noting its 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?

The input schema has zero parameters, and schema description coverage is 100%. With 0 params, the baseline score is 4, and the description adds no additional parameter info 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 'List logged investigation experiments', which specifies the verb (List) and the resource (logged investigation experiments). Among sibling tools like investigation_add and investigation_log_experiment, it uniquely identifies its function.

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

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

The description provides no guidance on when to use this tool versus alternatives like investigation_list or investigation_log_experiment. No explicit when/when-not or alternative recommendations 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 exist, and the description provides no behavioral details (e.g., side effects, idempotency, auth requirements). It only lists parameters without explaining what the tool does beyond logging.

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?

One sentence front-loads the action but could be more concise or include additional context. Adequate length but not optimally 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?

The description lacks prerequisite information (e.g., how an investigation ID is specified) and does not summarize the output schema. For a 5-parameter tool, it is incomplete.

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

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

Schema coverage is 0%, so description must compensate. It names the parameters (hypothesis, methodology, results, conclusion) but adds no meaning beyond the property names, e.g., not describing the 'results' object structure.

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

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

The description clearly states the tool logs a structured experiment within an investigation, listing components. It distinguishes from siblings like investigation_add and investigation_get, though not explicitly contrasted.

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

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

No guidance on when to use this tool versus alternatives like investigation_add or investigation_delete_experiment. The context of use within an investigation is implied but not elaborated.

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

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

With no annotations, the description should disclose behavioral traits like side effects or permissions. It only states 'Append journal entry', omitting that it modifies state, requires authentication, or has limits. This is minimally informative.

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 (3 words), but at the cost of missing critical information. It is not front-loaded with the most important usage context.

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

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

Given the presence of sibling tools and a moderately complex input schema (3 parameters, output schema exists), the description is too sparse. It does not explain what the output contains or how the tool fits into the overall journal workflow.

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

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

Schema description coverage is 0%, and the description adds no parameter-level meaning. Parameters like entry_type, content, and tags are left entirely to the schema, which lacks individual descriptions. The description fails to compensate for this 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?

Description 'Append journal entry' uses specific verb and resource, clearly indicating an add operation. It distinguishes from siblings like journal_delete or journal_get, though no explicit differentiation is provided.

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 journal_list or journal_search. Users must infer usage from the tool's 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 provided, so description carries full burden. It states 'hard-delete' implying permanent removal and mentions confirmation requirements. But it does not describe potential side effects or data loss implications.

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

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

Two sentences, front-loaded with action. Every sentence adds value. 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?

Covers main action and critical conditions. Output schema exists, so return values are covered. Lacks mention of error handling or what happens if entry_id doesn't exist.

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 has 0% description coverage. Description adds meaning by stating entry_id is the identifier and specifying confirmation requirements with conditions. Could be improved by describing entry_id format.

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

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

Clearly states 'Hard-delete a journal entry by entry_id', which is a specific verb+resource. It distinguishes from sibling tools like journal_append, journal_get, journal_list, journal_search.

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

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

Explicitly requires confirm=True and confirm_production=True in production. However, it does not provide guidance on when to use this tool versus alternatives (e.g., if a soft delete exists).

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 bears full responsibility for behavioral disclosure. It fails to mention any traits such as read-only nature, error conditions, or return format. 'Get journal entry' is insufficient for an agent to understand behavior.

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

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

The description is a single sentence with no waste, but it sacrifices informativeness for brevity. It is concise but under-specified, offering minimal value beyond the tool name.

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 required parameter and an output schema, the description should at least link the parameter to the entry identifier. It does not, leaving the agent without enough context to properly use the tool.

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

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

The schema description coverage is 0%, and the description does not explain the `entry_id` parameter. The agent must infer its purpose from the name alone, which is inadequate for correct invocation.

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 'Get journal entry' provides the verb and resource, but it is essentially a tautology of the tool name. It does not clarify that it retrieves a single entry by ID, which distinguishes it from siblings like `journal_list` and `journal_search`.

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

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

No guidance is given on when to use this tool versus alternatives like `journal_list` or `journal_search`. The agent receives no hints about the appropriate 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, and the description does not disclose behavioral traits such as pagination, sorting, or that it returns a list. The limit parameter is not explained, and important behavior like output format is 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 extremely concise (3 words) and front-loaded. However, it is under-specified; brevity does not serve usefulness. A bit more context (e.g., 'Lists recent journal entries, default 20') would improve without losing conciseness.

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

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

Given the presence of an output schema and many sibling tools (e.g., journal_search, journal_get), the description is insufficient. It does not explain how the output is structured or how this tool relates to others. The agent needs more context to use it effectively.

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 and the description does not mention the 'limit' parameter at all. The agent must infer from the schema that limit controls the number of entries, but no semantic context is added beyond the default 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 'List journal entries' clearly indicates a verb (List) and resource (journal entries), distinguishing it from journal_get (single entry) and journal_search (filtered search). The purpose is clear but lacks precision on whether it lists all or recent 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?

No guidance is provided on when to use this tool versus alternatives like journal_search (which filters) or journal_get (single entry). The description does not help an agent choose 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?

The description does not disclose any behavioral traits beyond the basic search operation. Since no annotations are provided, the description should cover aspects like whether it is read-only, pagination, or sorting behavior. It fails to do so.

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

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

The description is a single sentence and thus concise, but it is too brief to be helpful. It lacks structure or prioritization of key information.

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

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

Given the schema has 5 parameters with no descriptions and no annotation support, the description is woefully incomplete. It does not explain the search semantics, filtering options, or return format despite the existence of an 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?

The schema has 0% description coverage, and the tool description adds no meaning to any parameter. It does not explain the purpose of fields like query, limit, entry_type, or date ranges, leaving the agent to infer from names alone.

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

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

The description clearly states the tool performs full-text search across journal entry content. It uses a specific verb+resource (search across journal entries) and implicitly distinguishes from sibling tools like journal_list and journal_get that serve different purposes.

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

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

No guidance is provided on when to use this tool versus alternatives like search_local or search_corpora. The description does not include any context about prerequisites, exclusions, or comparison with related 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 available, the description carries full burden for behavioral disclosure. It only says 'Add a knowledge base entry' without revealing mutation effects, authentication needs, rate limits, or potential data loss. This is insufficient for a write operation.

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

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

The description is a single sentence with no redundancy, but it is too brief to be effective. While concise, it sacrifices necessary information for brevity.

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

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

Given the tool has 7 parameters, 3 required, and an output schema, the description is incomplete. It does not explain return values, side effects, or how parameters interact, making it insufficient for reliable 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 must explain parameters. It does not mention any of the 7 parameters (topic, title, content, tags, etc.) or their semantics, leaving the agent with no understanding of required inputs.

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 'Add a knowledge base entry' clearly states the action (add) and the resource (knowledge base entry), which distinguishes it from sibling tools like kb_delete or kb_get. However, it could be more specific about the type of entry being added.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites, context, or exclusions, leaving the agent with no decision support.

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

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

Discloses idempotency and skipping behavior based on content hash. No annotations provided, so description carries the burden; it adds meaningful behavioral context beyond schema.

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

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

Two efficient sentences with no wasted words. Front-loaded with action and condition.

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?

Lacks parameter documentation and output schema description. With 4 parameters and no coverage, the description is incomplete for proper 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%, and the description does not mention any of the 4 parameters (batch_size, limit, dry_run, confirm_production), failing to compensate for the 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?

Clearly states the verb 'embed' and resource 'KB entries that are missing or stale', with specific condition (model/content changed). Distinguishes from siblings like kb_embedding_status or kb_add.

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?

Implies usage for refreshing stale embeddings but does not explicitly state when to use versus alternatives (e.g., kb_ingest_* or kb_update). Only mentions a prerequisite environment variable.

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 merely repeats the action without disclosing behavioral traits like destructive nature, the need for confirmation, or side effects. It adds little beyond the tool name.

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?

One sentence with no redundancy, but extremely minimal. It is concise at the expense of necessary 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?

Given the tool's destructive nature and the confirm parameter, the description lacks essential context such as the permanence of deletion and the role of confirm. The output schema exists but does not compensate for the missing behavioral context.

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

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

Schema description coverage is 0%, and the description provides no information about parameters (kb_id, confirm) beyond what the schema defines. This is a critical 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 action ('Delete') and the resource ('existing KB entry from database'), distinguishing it from sibling tools like kb_add (create) and kb_update (modify).

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

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

No guidance on when to use this tool versus alternatives, no mention of irreversibility or prerequisites. Only implied usage from the name.

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 describes what is reported but does not mention any behavioral traits like read-only nature or permissions. Adequate but minimal.

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

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

Single concise sentence that front-loads the purpose and enumerates outputs. No unnecessary words.

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

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

For a parameterless tool with output schema, description lists all key outputs. No gaps given tool simplicity.

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, so schema provides nothing. Description adds value by explaining the report contents beyond an 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?

Description clearly states verb (Report) and resource (embedding coverage). Lists specific data points, distinguishing it from sibling tools like kb_sync_status.

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 or when not to use. Purpose implies it's for checking embedding status, but no alternatives 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?

No annotations are provided, so the description bears full responsibility. It mentions 'full' KB entry but does not explain what that entails (e.g., all fields, read-only nature). Lacks side-effect or authorization details.

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

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

One sentence, front-loaded, no redundancy. Every word serves a 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 an output schema exists and the tool is simple (1 param), the description is minimally adequate. However, more context about what 'full' means could 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?

With schema description coverage at 0%, the description should compensate. It adds 'by ID' but the schema already indicates the kb_id parameter. No format or constraints added beyond the schema.

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

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

The description clearly states the verb 'Get', resource 'KB entry', and scope 'by ID'. It effectively distinguishes this tool from siblings like kb_list and kb_search.

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

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

No guidance on when to use this tool versus alternatives. With many sibling tools for KB operations, the description does not indicate when get is appropriate over list or search.

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

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

No annotations provided; description only says 'Fetch full content' without stating whether it's read-only, safe, error behavior, or permission requirements. Limited behavioral insight.

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

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

Two sentences, front-loaded with action, then usage advice. No filler; every word earns its place.

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

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

Covers purpose and usage guidance adequately for a simple tool with output schema, but lacks behavioral and parameter details. Gaps in transparency and parameter semantics reduce completeness.

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

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

Schema description coverage is 0%, and the description adds no parameter meaning or constraints beyond the schema (e.g., max 50 items not mentioned, no format guidance).

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

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

Description clearly states the action ('Fetch full content') and resource ('multiple KB entries by ID'), distinguishing from sibling kb_search by advising use after search to avoid N+1 round trips.

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

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

Explicitly recommends using after kb_search and explains benefit (avoid N+1). Does not mention when not to use or list alternatives beyond the sibling, but context is clear.

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

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

No annotations exist, so description must cover behavior. It lacks details on atomicity, overwrite behavior, error handling, or required 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?

Single sentence is concise but overly terse; lacks front-loading of critical 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?

Despite having an output schema and 8 parameters, the description explains nothing about return values, parameter effects, or prerequisites, making it very incomplete.

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

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

Schema coverage is 0%, and the description adds no meaning to any of the 8 parameters. It only repeats the basic purpose.

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

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

Clearly states the tool ingests a directory of markdown files in batch. Among siblings, kb_ingest_doc handles single files, so this distinguishes as batch directory ingestion.

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?

Implies usage for directory ingestion but provides no explicit when-to-use or when-not-to-use guidance, nor comparisons to alternatives like kb_ingest_doc.

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

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

No annotations provided, so description must carry full burden. It mentions change detection but does not explain what that entails (e.g., whether it checks for changes, how conflicts are handled). No disclosure of permissions, rate limits, or side effects beyond ingestion.

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 (one sentence) and front-loads the primary action. However, it sacrifices necessary detail, making it borderline under-specified.

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 7 parameters, no schema descriptions, no annotations, and an existing output schema, the description is severely lacking. It does not clarify return values, change detection mechanics, or parameter interactions, leaving the agent with insufficient context for reliable 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%, yet the description provides no explanation for any of the seven parameters (e.g., strategy, chunk_size, tags, overwrite, author, source_type). The agent has no insight into parameter purpose or constraints.

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

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

The description clearly states the tool ingests a single markdown file into KB with change detection, distinguishing it from directory-level operations like kb_ingest_dir and other KB tools.

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

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

No guidance on when to use this tool versus alternatives like kb_ingest_dir or kb_update. The mention of 'change detection' is vague and not explained in context of use cases.

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

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

No annotations are present, so the description must disclose behaviors. It only states the operation without mentioning that it is read-only, whether it requires special permissions, or any other behavioral traits.

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 only three words, which is too brief. While concise, it sacrifices informativeness; every word should add value beyond the name, but here it does not.

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 three parameters and sibling tools, the description should cover pagination and filtering. Although an output schema exists, the description is incomplete without explaining the tool's scope and usage context.

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

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

Schema description coverage is 0%, and the description adds no meaning to the parameters (topic, limit, offset). It does not explain the optional topic filter or pagination behavior, leaving the agent without guidance.

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

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

The description 'List KB entries' is clear about the verb and resource, but it is vague as it does not differentiate from sibling tools like 'kb_search' or 'kb_get'. It omits scope or filtering capabilities hinted by parameters.

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 like 'kb_search' (for queries) or 'kb_get' (for single entry). The description lacks any context for selection.

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

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

No annotations are provided, so the description must convey behavior. It describes the default lexical search and the optional vector modes with RRF fusion, but fails to mention what happens if the required env var is missing, or any error handling. It does not discuss rate limits, authentication, or side effects, though search is read-only.

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

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

The description is a single sentence that efficiently conveys the core functionality and key options. It is concise but could benefit from brevity in technical details; overall, it is 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?

Given the tool's complexity (12 parameters, multiple search modes, an output schema exists), the description is incomplete. It does not explain many parameters, output format, error conditions, or how the default fallback works. The reliance on technical terms (FTS5, RRF fusion) may also assume too much prior knowledge.

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

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

Schema description coverage is 0%, so the description must explain parameters. It only covers 4 of 12 parameters (query, semantic, hybrid, search_mode), leaving important params like top_k, session_id, min_score, etc. unexplained. This insufficiently compensates for the lack of schema descriptions.

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

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

The description states 'Search knowledge base' and details the search modes (FTS5, semantic, hybrid), clearly identifying the tool's function. The name 'kb_search' combined with the description distinguishes it from sibling tools like 'search_local' or 'search_corpora', though it could be more explicit about when to use this over other search tools.

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

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

The description explains how to enable semantic/hybrid search (setting flags and requiring an environment variable). However, it does not specify when NOT to use this tool or direct users to alternatives like 'multi_search' for broader searches, lacking comprehensive usage 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 fully bears the burden of behavioral disclosure. It only says 'Check sync state', which implies a read-only operation, but does not detail what the response contains, potential costs, or side effects. The output schema exists but is not referenced.

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

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

The description is a single short sentence, which is concise but lacks structure such as paragraphs or bullet points. It is front-loaded with the core purpose, but could be improved with additional context without becoming verbose.

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 (1 optional parameter, output schema present), the description still falls short. It fails to explain the parameter or reference the output schema, leaving the agent with incomplete context for effective use.

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

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

The input schema has one optional parameter (dir_path) with 0% description coverage. The description does not explain the parameter's purpose, meaning 'dir_path' is opaque to the agent. This fails to add 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?

Description states 'Check sync state between source docs and KB', clearly identifying the verb (check) and resource (sync state). It distinguishes itself from sibling tools like kb_add or kb_embedding_status by focusing on synchronization status, though it could be slightly more specific about what 'sync state' entails.

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. It does not mention prerequisites, context, or exclusions, leaving the agent without decision support for tool selection.

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

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

No annotations are provided, so the description must fully convey behavioral traits. It states the tool updates fields but does not disclose whether partial updates preserve other fields, required permissions, side effects (e.g., re-embedding), or error handling. The presence of an output schema mitigates return value documentation but not 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 a single sentence that efficiently conveys the action, resource, and scope of modification. It is front-loaded and contains no unnecessary words or repetition.

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

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

Given the tool's complexity (7 parameters, mutation action) and lack of annotations, the description is incomplete. It does not address when to use the tool, prerequisites, or behavioral details like partial updates or side effects. The output schema helps with return values but does not compensate for missing contextual guidance.

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

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

With 0% schema description coverage, the description should add meaning to each parameter beyond the property name. It merely lists the same field names (content, title, topic, tags, verified state, trust_score) without explaining formats, constraints, or semantics (e.g., what 'verified state' means). This provides 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 uses the specific verb 'Update' and identifies the resource as 'existing KB entry', clearly distinguishing it from sibling tools like kb_add (create) and kb_delete (delete). It also lists the updatable fields, making the tool's functionality 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 use when modifying a KB entry but provides no explicit guidance on when to use this tool versus alternatives (e.g., when to use kb_add instead) or any prerequisites. The implied context is clear but lacks exclusions or rationale.

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

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

Discloses that omitted fields cannot be reset to null and the environment dependency. However, no annotations exist, so the description must fully cover behavioral traits. It lacks details on side effects, idempotency, and return value (though output schema may cover return).

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

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

Two sentences, front-loaded with purpose. Every sentence adds value: purpose, field behavior, environment requirement. 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 an output schema exists (presumably documenting return values), the description covers purpose, field semantics, update behavior, and environment requirement. Missing broader context like typical usage workflow or interpretation of scores, but mostly complete for a feedback logging 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 description must add meaning. It lists the three optional fields but does not explain valid values, ranges, or formats for user_feedback_score or required_requery. The query_id format is not specified. Only minimal semantic help.

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

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

Clearly states the tool scores/annotates a prior kb_search result by query_id. Mentions retrieval telemetry context, distinguishing it from sibling tools like get_retrieval_telemetry which only retrieve data. Slight jargon ('issue #5') reduces clarity slightly.

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?

Explains what can be supplied (feedback score, requery, notes) and that omitted fields are left unchanged. Also warns that the tool has no effect unless LORE_HARD_NEGATIVE_MINING=true on PostgreSQL backend. Does not explicitly state when not to use it or mention alternatives.

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 full burden. It only states 'get all tools' without explaining what constitutes 'tools', whether the operation is idempotent, or what the response contains. An output schema exists but the description adds no behavioral context.

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

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

While short, the description is under-specified. It lacks necessary details like parameter usage, return format, or alternative tools. Conciseness should not sacrifice completeness.

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

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

Given the tool has one parameter and an output schema, the description should be straightforward but is too minimal. It does not explain what 'all tools' means or how to interpret the result. Sibling tool names suggest a family of MCP index operations, but no context is 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?

The schema has a single required parameter 'server_id' with no description or type constraints (e.g., format, example). The description does not elaborate on what a server_id is or how to provide it. Schema description coverage is 0%, so no help from schema either.

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

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

The description clearly states the verb 'Get' and the resource 'all tools for a specific MCP server'. It distinguishes itself from siblings like 'mcp_index_get_tool' which likely gets a single tool.

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

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

The description provides no guidance on when to use this tool versus alternatives like mcp_index_get_tool or mcp_index_search. There is no mention of context, prerequisites, or exclusions.

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

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

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It fails to mention that this is a read-only operation, whether it has side effects, or any rate limits or authentication requirements.

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

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

The description is very short (one sentence), which is concise but lacks necessary detail. It is not wasteful, but the conciseness comes at the cost of 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?

Although an output schema exists, the description is incomplete because it omits parameter guidance and behavioral context. For a simple get tool, more context is needed to ensure correct usage, especially given the lack of annotations.

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 for the only parameter 'tool_name'. The tool description adds no additional semantics, such as what format the name should be in or how to obtain valid 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 clearly states the tool retrieves detailed information about a specific tool. However, it does not differentiate itself from sibling tools like mcp_index_get_server or mcp_index_search, which could be confusing.

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. For example, it doesn't mention that this should be used when you have a tool name and need its full definition, as opposed to searching for tools with mcp_index_search.

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

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

With no annotations, the description carries the full burden. 'Force rebuild' implies a destructive or heavy operation, but no details on side effects, safety, permissions, or output behavior beyond the vague equivalence to another tool. The behavioral impact is underspecified.

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

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

The description is extremely concise at 7 words, but it wastes the opportunity to add value. It is front-loaded but could be more informative without losing brevity.

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

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

Given a simple tool with no parameters, the description minimally covers the purpose. However, it lacks details on return values (despite output schema existing) and fails to provide complete context for a rebuild operation. It is adequate but not thorough.

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 no parameters, so baseline is 4. The description does not need to add parameter details since none exist, and the coverage is 100%.

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

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

The description states 'Force rebuild of entire MCP index', clearly identifying the verb (rebuild) and resource (MCP index). However, it adds 'same as mcp_index_scan', equating it to a sibling without differentiating. This reduces clarity about when this tool is distinct.

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 like mcp_index_scan. The description merely states it is the same as a sibling, which could confuse agents about which to invoke.

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

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

No annotations are provided, so the description must carry full burden. It discloses token savings (66%) but fails to mention side effects like whether the index is overwritten or appended, or any permissions needed. This is insufficient for a tool performing a potentially expensive operation.

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

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

The description is a single efficient sentence that front-loads the action and includes a key benefit (token savings). It wastes no words, though it could benefit from brief parameter explanations.

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) and two undocumented parameters, the description lacks completeness. It doesn't explain output structure, parameter behavior, or usage context beyond the default. A more thorough description is needed for a scan 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%, and the description does not explain any parameters (triggered_by, config_filter). The schema alone provides default values but no semantic context, so the agent gets no added value from the description.

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 ('Scan all MCP servers and index their tools') and distinguishes from siblings like mcp_index_rebuild by noting the default behavior (configured servers only). This provides a specific verb and resource 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 implies when to use (scanning with config_filter default) but does not explicitly state alternatives or when not to use. There is no guidance on trade-offs versus mcp_index_rebuild or other scanning 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 carries full burden for behavioral transparency. It only states the purpose, omitting details like read-only nature, authentication needs, rate limits, or return format. The presence of an output schema is not leveraged in the description.

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 (7 words), but it sacrifices essential information. While it is front-loaded with the key action, it lacks detail that would make it genuinely helpful for an agent. It earns a middle score for efficiency but not for informativeness.

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 three parameters, the existence of an output schema, and the large set of sibling tools, the description is incomplete. It fails to explain the category filtering, limit usage, or return structure, making it insufficient for an agent to use correctly without additional context.

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

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

Schema description coverage is 0%, so the description must compensate. It does not explain the meaning of 'query', 'category', or 'limit' beyond their names. The values and constraints (e.g., category being nullable, limit defaulting to 20) are only in the schema, not described.

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: searching for MCP tools by description/capability. It uses a specific verb ('search') and resource ('MCP tools'), and implicitly distinguishes from sibling search tools like 'journal_search' and 'kb_search' which target different resources.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention context, prerequisites, or when not to use it, which is critical given the many sibling search 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 behavioral traits. It only states basic operation and result combination, lacking details about limitations, ordering, deduplication, or performance. Minimal 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?

Three sentences with no wasted words. First sentence states purpose, second states result, third provides usage alternatives. Efficient and well-structured.

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

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

The tool is simple with one parameter and an output schema. The description covers scope and alternatives but omits details on result merging behavior. Slight gap but mostly complete given the context.

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

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

Schema description coverage is 0% for the only parameter 'query'. The description adds that it is a 'single query', but provides no further details on format, length, or constraints, which is insufficient to compensate for the lack of schema description.

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

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

The description explicitly states 'Search across all configured sources simultaneously' with specific source types listed, and directly contrasts with sibling tools for single-source searches, providing clear 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?

The description provides explicit guidance: 'For searching within a specific source only, use kb_search, search_local, search_transcripts, or search_corpora instead.' This clearly indicates when to use this tool and when to use alternatives.

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 that the tool writes to knowledge.hard_negative_pairs and requires LORE_HARD_NEGATIVE_MINING=true. However, it does not mention if the operation is idempotent, potential side effects (e.g., does it delete existing pairs?), or error behaviors. The core behavior is clear 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?

Three sentences, no wasted words. First sentence defines purpose, second adds usage context, third states a prerequisite. Efficient and well-structured, fitting more information into a compact form.

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

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

Given simple parameters and existing output schema, the description covers core functionality, parameters, and a prerequisite. It lacks explicit guidance on the format for the 'since' parameter or error conditions. However, the output schema likely covers return values, so completeness is 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 must compensate. It explains both parameters: 'since' is for incremental refresh and 'dry_run' returns counts without writing. This adds needed meaning beyond the schema's raw structure. The explanation is sufficient but could specify the expected format for 'since' (e.g., ISO timestamp).

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 scans retrieval telemetry and upserts hard negative pairs into a specific table. The verb 'scan' and 'upsert' precisely describe the action, and the resource 'knowledge.hard_negative_pairs' is explicit. This distinguishes it from siblings like get_hard_negatives (which retrieves) and get_retrieval_telemetry (which only scans).

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

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

The description provides clear usage hints: 'Use since= for incremental refresh' and 'dry_run=true returns counts without writing.' It also notes a required environment variable. However, it does not explicitly state when not to use this tool compared to alternatives, missing a chance to guide selection 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?

With no annotations, the description fails to disclose behavioral traits such as return format, pagination, side effects, or any rate limits. The minimal description does not add value beyond naming the resource.

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

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

The description is very short (one phrase). While concise, it sacrifices necessary detail. It front-loads the key info but lacks structure for a search tool.

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

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

Given the presence of an output schema, the description does not clarify what the search returns (e.g., matches, scores, metadata). For a search tool, this omission leaves the agent uncertain about expected results.

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

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

Schema description coverage is 0%, and the description does not elaborate on the parameters 'query' or 'corpus_ids'. Their meanings, formats, and constraints are left entirely to the agent to infer from the 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 action (search) and the resource (corpus manifests in JSONL files). It distinguishes from sibling tools like search_local and search_transcripts by specifying the target data type.

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

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

No guidance on when to use this tool vs alternatives. It does not mention when not to use it or provide context about its suitability for different scenarios.

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

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

No annotations are provided, so the description carries full burden. It only states 'search local files by content', implying read-only, but no details on permissions, rate limits, or side effects. Missing key behavioral context.

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

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

Extremely brief but at the cost of informativeness. A single phrase does not convey enough detail for a tool with multiple parameters and siblings.

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

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

Given 3 parameters (one required) and no parameter descriptions or behavioral annotations, the description is insufficient. Output schema exists but is not referenced. Agent lacks 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 coverage is 0%, yet the description provides no parameter details. The 'query', 'paths', and 'file_types' parameters are left unexplained, forcing the agent to infer their meaning from names alone.

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

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

The description clearly states the action (searching local files) and mode (lexical), distinguishing it from semantic search or other search tools. However, 'lexical mode' is not explained, mildly reducing clarity.

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

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

No guidance on when to use this tool versus many sibling search tools like 'search_corpora', 'kb_search', or 'multi_search'. The description does not provide context for appropriate use.

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

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

With no annotations, the description carries full burden but only states the basic function. It fails to disclose behavioral traits like idempotency, error handling, or any side effects.

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

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

The description is short and to the point, but it is too minimal. It could include more detail without being verbose. The single sentence structure is efficient but incomplete.

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 existence of an output schema and multiple param options, the description lacks completeness. It does not mention output format, pagination, or any constraints on the search.

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

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

Schema description coverage is 0%, and the description adds no meaning beyond the schema. The 'speaker' parameter is not explained, and 'query' is only implied as a search term.

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 searches transcript segments from Whisper outputs, differentiating it from other search tools like kb_search or search_corpora. However, it could be more precise about what constitutes a segment.

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

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

No guidance is provided on when to use this tool versus alternatives such as multi_search or kb_search. The description lacks context on preferred use cases or exclusions.

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

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

No annotations are provided, and the description fails to disclose any behavioral traits such as side effects, permissions, or output; it only restates the tool name, providing no value beyond the structured fields.

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

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

The description is extremely short (three words), but it fails to convey useful information; it is under-specified rather than concise, and does not earn its place by aiding tool selection or invocation.

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

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

Given the lack of annotations, no parameter descriptions, and an output schema that is not described, the description is severely incomplete; it does not cover essential aspects like what the tool does, what the parameters mean, or what the output 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?

With 0% schema description coverage and no parameter explanation in the description, both 'config_name' and 'config_data' are left completely unexplained; the description adds nothing to understand their purpose or format.

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

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

The description 'Snapshot current config' suggests a verb+resource but is vague; 'snapshot' implies capturing existing state, yet the required input 'config_data' contradicts this by asking for data to be provided, causing confusion about the tool's actual function.

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 or why to use this tool over siblings; the description offers no context or exclusions, leaving the AI agent to infer usage without any hints.

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