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

With no annotations, the description carries the full burden of behavioral disclosure. It only states the mutation action ('Attach') without revealing side effects, permissions, idempotency, or how the evidence is stored/associated. 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, clear sentence with no redundant words. It is efficient and front-loaded, though it could be slightly expanded 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?

The description is too thin for a mutation tool with 4 parameters and no annotations. Although an output schema exists, it does not compensate for missing parameter semantics, usage guidance, or behavioral context, making the tool description incomplete for an agent.

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

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

Schema description coverage is 0%, so the description must compensate. It gives examples of what 'content' might be (log excerpt, output, note) but does not explain the roles of case_id, summary, or filename, leaving agents to guess their meaning.

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

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

The description uses a specific verb 'Attach' with the resource 'evidence' and target 'a case', clearly distinguishing it from siblings like case_create or case_update. The parenthetical examples (log excerpt, output, note) add useful specificity without ambiguity.

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

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

No usage guidance is provided. The description does not state when to use this tool versus alternatives like case_update or case_create, nor does it offer any context about prerequisites, complementary tools, or when adding evidence is appropriate.

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

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It only mentions the parameter format and the 'not yet validated' condition, but omits details about creation side effects, return values, permissions, or default state. This is a significant gap for a mutation tool.

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

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

The description is two sentences with no fluff. The first sentence states the core purpose, and the second provides a targeted parameter hint. It is front-loaded and efficient.

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

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

Despite having an output schema, the description does not provide adequate context for a create operation with 5 parameters and no annotations. It lacks prerequisites, expected outcomes, error handling, or any indication of the case lifecycle beyond the 'not yet validated' usage hint. The description is too sparse to be complete.

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

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

Schema description coverage is 0%, so the description must compensate. It only adds meaning for 'tags' and 'references' by clarifying they are comma-separated strings, while leaving 'title,' 'goal,' and 'context' entirely to inference. This partial coverage is insufficient given the low schema baseline.

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

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

The description clearly states 'Create an investigation case,' which is a specific verb and resource. This distinguishes it from sibling tools like case_update and case_promote, and the phrase 'investigation case' adds domain specificity.

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

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

The description explicitly provides a usage condition: 'Use this when a topic is not yet validated.' This gives clear context for when to invoke the tool, but it does not explicitly mention alternatives or when-not-to-use scenarios, so it falls short of a 5.

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

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

With no annotations provided, the description carries the disclosure burden. The verb 'Read' clearly indicates a non-destructive operation, and the example ID provides context about the resource. However, it omits details like error handling (e.g., not found) or authorization, but for a simple getter this is sufficient.

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

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

The description is a single, compact sentence with a helpful example. It is front-loaded with the action ('Read') and resource ('case'), and every word earns its place. 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?

Given the simplicity (1 parameter, output schema exists), the description is adequately complete. It identifies the exact use case (fetching by ID) and provides an example. Missing explicit comparison to sibling tools, but the overall context is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It adds value by providing an example ID format ('case-2026-08-07-001') which clarifies the expected string structure. However, it doesn't elaborate on the semantics beyond that, leaving some ambiguity about whether the ID is the full path or a simple key.

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

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

The description clearly states the tool's function: 'Read a case by its id' with a concrete example ID format ('case-2026-08-07-001'). This distinguishes it from sibling tools like case_list (listing) and case_search (searching), making the purpose unambiguous.

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

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

The description implies usage when you have a specific case ID, which is clear context. It doesn't explicitly name alternatives (e.g., 'use case_search to find cases by criteria'), but the phrase 'by its id' effectively communicates that this is the direct-fetch tool, distinct from list/search variants.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a read-only operation via 'List' and documents the filter options, but it does not mention any other behavioral traits such as pagination, ordering, rate limits, or scope constraints. The description is adequately transparent for a simple list operation, but lacks depth.

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

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

The description is a single concise sentence that front-loads the core action ('List cases') and immediately adds the filtering options. Every word earns its place, and there is no redundancy or filler.

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

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

Given that the tool has a simple two-parameter schema, an existing output schema (so return values need not be described), and a clear list operation, the description is nearly complete. It could be improved by mentioning ordering or pagination behavior, or by contrasting with case_search, but for its simplicity, it is sufficiently complete.

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

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

The input schema provides no descriptions for the parameters (0% schema coverage), so the description must compensate. It clearly explains that both parameters are optional filters, and it enumerates the valid values for status (open/in_progress/resolved/abandoned). The tag parameter is described as a filter, which adds meaning beyond the raw schema, though it does not specify matching semantics (e.g., exact vs. partial).

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

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

The description states 'List cases' which is a specific verb+resource, clearly indicating it returns a collection of cases. It also mentions optional filters, which adds specificity. However, it does not explicitly distinguish itself from sibling tools like case_search or case_get, though the naming and phrasing make the purpose reasonably clear.

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: to list cases with optional filtering by status and tag. However, it provides no explicit guidance on when to use this tool versus alternatives like case_search or case_get. There are no stated exclusions or alternative recommendations, so while the context is clear, the guidance is limited to implied usage.

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

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

With no annotations, the description carries the disclosure burden. It reveals side effects: writes MD/SKILL.md, writes to KB, and marks the case. This goes beyond a simple 'promote' and gives useful behavioral context, though it doesn't mention overwrite behavior or permissions.

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

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

The description is two sentences, front-loaded with the main purpose and followed by specific actions. Every sentence is essential with no fluff or repetition.

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

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

The description covers the core behavior thoroughly for a simple tool. It explains what it generates, where it writes, and that it marks the case. It doesn't detail return values or error cases, but given the output schema exists (not shown) and the tool's moderate complexity, this is reasonably complete.

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

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

Schema coverage is 0%, but the description explains 'target = fiche or skill', clarifying the valid values for the target parameter. case_id is not explicitly described but is self-explanatory. This adds some meaning beyond schema, but lacks detail on the 'marks the case' effect or any parameter 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's purpose: 'Promote a resolved case into validated KB' with specific actions 'Generates the MD/SKILL.md from the case, writes it to the KB and marks the case.' It distinguishes from siblings like case_set_status or fiche_write by describing the promotion workflow.

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 a case is 'resolved' and you want to validate it into the KB, with 'target = fiche or skill' indicating the KB entry type. It doesn't explicitly mention alternatives like fiche_write, but the context is clear enough for most agents.

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

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

With no annotations, the description must carry the full burden of behavioral disclosure. It only states the scope (cases and KB) and a usage hint, but does not mention whether the operation is read-only, how results are returned, pagination, or any limitations. This is minimal behavioral transparency.

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

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

The description is two short sentences, front-loaded with the core purpose and then a usage directive. No filler words; every clause 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?

The output schema likely covers return structure, and the description gives purpose and when-to-use. However, it leaves parameter semantics completely to the bare schema and provides no behavioral details. For a simple search tool this is minimally viable but still has clear gaps.

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

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

Schema description coverage is 0%, and the description does not mention either parameter. There is no guidance on the expected format of 'query' or the meaning/effect of 'top_k'. The agent must guess parameter semantics from names alone, which is insufficient.

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

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

The description clearly states the tool performs 'semantic search across cases and KB', using a specific verb and resource. This distinguishes it from sibling tools like case_list and case_get, which are likely structured lookups rather than semantic search.

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

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

The instruction 'Use this FIRST when debugging or planning' provides clear contextual timing for when this tool is preferred. It does not explicitly mention when not to use it or name alternatives, but the guidance is actionable and sets expectations.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the action 'Change' and the allowed statuses, but does not mention permissions, validation behavior, side effects, whether the change is reversible, or how errors are handled. This is a significant gap for a mutation tool.

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

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

The description is a single, front-loaded sentence with no redundant words. It conveys the core purpose and the allowed values efficiently, earning a perfect score.

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

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

Given the low complexity (2 required params, output schema present, no nesting), the description covers the core functionality and enumerates status options. However, it fails to address when to use this vs. the overlapping sibling case_update, and it provides no context about edge cases or expected behavior. It is minimally complete but has clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It does by explicitly enumerating the valid status values, which is essential information missing from the schema. The case_id parameter is self-explanatory from its name and the context. Little else is needed.

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 ('Change') and the resource ('case status'), and lists the allowed values (open/in_progress/resolved/abandoned). This makes the tool's specific purpose unambiguous and distinguishes it from the broader case_update sibling.

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 is given about when to use this tool versus alternatives. While the name and scope imply it is for status changes only, there is no mention of exclusions or when to prefer case_update over this tool. The usage context is only weakly implied.

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 and does disclose important field-level behavior (append vs. set vs. replace lists). It omits permission requirements, error behavior, and response details, leaving clear gaps for a mutating 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 front-loaded with a one-line action and followed by a tight, well-organized bullet list of field behaviors. Every line provides distinct information and there is no filler or repetition.

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

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

The description covers all supported field modes and field relationships (step_action/step_result pair) and correctly leaves return details to the existing output schema. It lacks explicit prerequisites and error conditions, but is otherwise complete for a field-update 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 input schema is opaque for fields (additionalProperties true, 0% description coverage), so the description’s enumerated list of supported fields with their value types and semantics is essential. It gives the agent concrete, actionable meaning beyond the raw schema.

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

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

The description clearly states the action as 'Append to a case' and lists the supported field categories, which gives a specific verb and resource. However, it does not explicitly differentiate itself from sibling tools like case_add_evidence or case_set_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?

The description provides no guidance on when to use this tool versus alternatives such as case_add_evidence or case_set_status. It only describes what fields can be updated, leaving the choice of tool implicit.

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 adds the 'validated' filter and the output format 'slugs', which is useful behavioral context beyond the tool name. However, with no annotations provided, it does not explain what 'validated' means, whether pagination exists, or any ordering behavior. This is 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?

The description is a single, concise sentence that front-loads the action and resource. Every word is informative; there is no fluff 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?

Given that the tool has no parameters and an output schema exists, the description covers the essential behavior (listing validated fiches) and hints at the output format. It is sufficiently complete for a simple list operation, though it lacks any caveats or usage scenarios beyond the bare description.

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

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

The input schema has zero parameters, so there are no parameter semantics to clarify. The description mentions 'slugs' as output, not input. According to the baseline for zero-param tools, a score of 4 is appropriate since no additional parameter explanation is needed.

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 ('List') and the resource ('validated fiches'), and specifies the output type as 'slugs'. This distinguishes it from sibling tools like fiche_read and fiche_write, which involve reading or writing individual fiches.

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 offers no guidance on when to use this tool versus alternatives. There is no mention of context, exclusions, or relationships to sibling tools like case_list or fiche_read. It merely states what it does, leaving usage entirely implied.

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 available, and the description offers no behavioral details such as what happens for invalid or unvalidated slugs, authentication requirements, or return value characteristics. The term 'validated' is ambiguous.

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 is concise, but it may be under-specified. It does include the qualifier 'validated' which adds some meaning, though not enough.

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, return values are not required in the description, but there is no context about what a fiche is, what 'validated' means, or error behavior. It lacks completeness for a tool with no 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 single parameter 'slug' is undocumented in the schema, and the description only mentions 'by slug' without explaining the format, source, or validation constraints. With 0% schema coverage, the description fails to compensate.

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 reads a fiche by slug, using a specific verb and resource. However, it does not explicitly differentiate from sibling tools like fiche_list or case_get, though the resource type 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?

There is no guidance on when to use this tool versus alternatives such as fiche_list or case_get. The implied usage is when a specific validated fiche slug is known, but no exclusions or comparison are provided.

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

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

With no annotations provided, the description carries the burden of disclosing behavioral traits. It explicitly mentions the 'overwrite' capability, which is a key destructive behavior. Yet it omits other important details such as required permissions, irreversibility, or response behavior, so the disclosure is only partial.

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

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

The description is two sentences with the first sentence front-loading the action and resource, and the second providing a useful pointer to an alternative. It is free of redundant words and every clause 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?

The description covers the core purpose and directs users away from the tool for validated knowledge, which is helpful. However, for a write tool with no annotations and minimal parameter guidance, it would benefit from explaining the nature of the content and the implications of overwriting. It is adequate but leaves meaningful gaps.

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

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

The input schema provides only type information for 'slug' and 'content' with 0% schema description coverage, and the description does not explain these parameters further. While the names are somewhat self-explanatory, no context is given for content format, slug uniqueness, or overwrite semantics, so the description adds little value beyond the schema.

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

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

The description clearly states the tool's function with specific verbs 'create' and 'overwrite' targeting the 'fiche' resource. The note 'Prefer case_promote for validated knowledge' distinguishes it from a sibling tool by indicating when a different tool is more appropriate.

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 to prefer 'case_promote' for validated knowledge, effectively stating a when-not-to-use condition and naming an alternative. However, it does not elaborate on specific scenarios where 'fiche_write' is the right choice, leaving some room for interpretation.

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

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

With no annotations provided, the description must disclose behavioral traits itself. It mentions 'Rebuild' and 'from all source files', but does not explain potential side effects like whether the existing index is replaced, if the operation is time-consuming, or if it can run concurrently with other operations. The return value is disclosed, but safety and impact traits are missing.

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, direct sentence that front-loads the action and scope. It contains no filler words or redundant information, making it highly concise 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?

Given the operation is potentially heavy (full index rebuild) and no annotations or detailed output schema are available, the description could provide more context about operational impact, prerequisites, or caution. However, the input is simple (no params) and the return value is stated, making it minimally complete but not fully comprehensive.

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

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

The tool has zero parameters, so the description does not need to explain any parameter semantics. The schema already accurately reflects this, and the rubric sets a baseline of 4 for zero-parameter tools, which is appropriate here since the description adds no unnecessary details.

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

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

The description clearly states the action ('Rebuild') and the resource ('vector index') with explicit scope ('from all source files'), making it specific and distinguishing it from sibling tools focused on case, fiche, and skill data. It also mentions the return value ('Returns doc count'), further clarifying its purpose.

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

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

No guidance is provided on when to use this tool versus alternatives, such as when a rebuild is necessary (e.g., after updating source files) or any caution about running it during production. The description simply states what it does without context for appropriate usage.

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

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

With no annotations, the description carries the full burden for behavioral disclosure. It adds some context by introducing 'validated' and 'slugs', but it doesn't state whether the operation is read-only, how the list is ordered or paginated, or any other behavioral traits like authentication requirements. This is a minimal addition 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?

The description is a single sentence that is direct and front-loaded with the action and resource. It contains no fluff or redundant information, and every part of the sentence adds value by specifying 'validated' and 'slugs'.

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

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

Given the tool's simplicity (no parameters, output schema present), the description is mostly adequate. However, it lacks usage context relative to sibling tools and doesn't clarify the meaning of 'validated' or whether the list is complete or paginated. This leaves some gaps for an agent invoking the tool in a complex 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?

The tool has zero parameters, so the baseline is 4. There is no need for parameter explanations in the description, and the empty input schema fully documents the absence of inputs, making the description sufficient in this dimension.

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

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

The description clearly states the tool lists validated skills and specifies that the output consists of slugs. The verb 'List' and resource 'skills' are specific, and the qualifier 'validated' adds a distinct scope. However, it doesn't explicitly distinguish itself from the sibling skill_read tool, relying on the verb to imply a list vs. read distinction.

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

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

There is no guidance on when to use this tool versus alternatives, such as skill_read or case_list. The description simply states what it does without providing context on typical use cases or exclusions, leaving the agent to infer 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 are provided, so the description must convey behavior. It states 'Read' implying a safe operation, but adds no detail about permissions, validation rules, return behavior, or error handling. The qualifier 'validated' is ambiguous.

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, seven words, immediately front-loaded with verb and resource. No filler.

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

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

The tool is simple with a single parameter and an output schema. The description gives the core purpose and identifier. Minor ambiguity around 'validated' could be clarified, but overall sufficient for a straightforward read operation.

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

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

Schema has one string parameter 'slug' with 0% description coverage. The description references it directly ('by slug'), giving it contextual meaning, but does not specify format or values 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 uses the specific verb 'Read' and identifies the resource 'skill' with a required identifier 'slug', clearly distinguishing from sibling tools like skill_list or fiche_read.

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

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

No explicit guidance on when to use this tool versus alternatives. The phrase 'by slug' implies the tool is for known identifiers, but no exclusions or alternative comparisons are provided.

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