RedM Mcp

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

Beyond the readOnlyHint=true annotation, the description discloses substantial behavioral traits: O(1) lookup against pre-parsed tables, typical latency (p50 ~15ms, p95 ~65ms), exact-match semantics (name/hash return 0 or 1), fuzzy trigram fallback behavior with the exact trigger condition, and the 'type' source-file nuance (same asset can appear under multiple types with different metadata). It even warns about decimal hashes and why fuzzy rarely fires without type narrowing. This is far more than the annotation provides and fully arms the agent.

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

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

The description is long but every section earns its place: purpose, return format, performance, not-for alternatives, parameter usage, type nuance, fuzzy behavior, and examples. It is front-loaded with the one-sentence purpose, uses clear section breaks and bullet lists, and avoids fluff. The length is appropriate for a tool with five parameters and nuanced edge cases; it reads as a compact reference rather than padded prose.

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 (5 parameters, 5 asset types, fuzzy matching, type source-file ambiguity), the description is remarkably complete. Even with an output schema present, the description explains the non-obvious return fields (matchType, variants, relationship, coords, etc.) and the exact conditions under which different metadata appears. It also covers edge cases like the same asset existing under multiple types and the decimal-hash rejection. There are no obvious gaps that would leave an agent unsure how to 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 coverage is 100%, so the baseline is 3, but the description adds critical semantics not present in the JSON schema: mutual exclusivity of name/hash/search (the schema does not enforce oneOf), the fact that 'limit' only applies to search, and the exact behavior of the fuzzy fallback (trigram similarity >=0.4, when it fires and when it doesn't). It also provides rich examples for each parameter (e.g., hash 0xBCFD0E7F resolves to a_c_bear_01) and clarifies the exact format expectations. This far exceeds what the schema already documents.

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

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

The description opens with a clear, specific statement: 'Resolve a RedM game-data asset (ped model, weapon, object, door, vehicle) by exact name, 32-bit hash, or partial-name search.' It explicitly distinguishes itself from sibling tools (lookup_native, grep_docs, semantic_search) in the 'NOT for' section, and even provides the exact output shape (type, name, normalized hash, source file, metadata). This goes well beyond a vague purpose and clearly differentiates from alternatives.

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 'NOT for' section lists three specific alternative tools with exact use cases (natives -> lookup_native, tokens -> grep_docs, behavior queries -> semantic_search). It also gives clear parameter usage rules ('Pass exactly ONE of name/hash/search'), explains when to use the optional 'type' filter, and includes concrete examples for each parameter mode. This is explicit, actionable guidance with no ambiguity.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description goes further by specifying the return shape '{path, title, chunks}[]' and explicitly clarifying that it does NOT do content search, adding meaningful behavioral context beyond the annotations. No contradiction exists.

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

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

The description is three sentences long, front-loaded with the purpose, then usage, then contrast, then return format. Every sentence carries essential information, and there is no fluff or repetition, achieving high conciseness and logical structure.

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 this is a simple enumeration tool with two optional parameters, read-only annotations, and no output schema, the description covers all needed aspects: purpose, usage, when-not-to-use, and return format. It is complete for the tool's complexity and 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 mention 'category/namespace' as scoping parameters, but it does not explain their distinct roles or how they interact. The ambiguity of the slash between category and namespace leaves their relationship unclear, though the enum for category provides some 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 explicitly states the tool enumerates doc paths within a category/namespace, using the specific verb 'enumerate' plus the resource 'doc paths'. It also distinguishes itself from sibling tools by explicitly contrasting with content searches and referencing alternatives, making its unique purpose 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 gives direct when-to-use guidance: 'discover what exists before calling get_document or grep_docs'. It also provides explicit when-not-to-use instructions and names alternatives (semantic_search for behavior/concept lookups, grep_docs for token lookups), fulfilling the usage guidelines dimension perfectly.

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 goes well beyond the `readOnlyHint: true` annotation by disclosing nuanced behaviors: fuzzy/leaf heading matching, auto-prepending the H2 parent's intro for deep headings, and keyed-catalog behavior where no heading lists top-level keys. It also reveals the 404 response format (available headings + cross-file hints), which is crucial for an agent to recover gracefully.

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 dense but every sentence earns its place, covering primary purpose, retrieval workflow, heading semantics, native/code-symbol alternatives, catalog patterns, and error behavior. It is front-loaded with the core action and progressively adds edge cases, with no fluff or repetition of schema details.

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 tool with no output schema, the description compensates by covering input semantics, return value expectations (full markdown or section), error recovery (404 hints), and edge cases like keyed catalogs and community paths. Combined with the rich input schema and readOnly annotation, the agent has everything needed to select and invoke this 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?

Although schema coverage is 100%, the description adds substantial meaning: it explains the `path` shape (`<category>/<file>.md` vs `learning:<id>`), warns against inventing `learnings/<slug>.md`, and clarifies that `heading` accepts either full breadcrumbs or leaf names, is case-insensitive and fuzzy, and must not be used for code symbols. This transforms bare parameter definitions into actionable 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 opens with a clear verb and resource: 'Fetch full markdown of a doc by `path`', and specifies exact source tools (`browse`, `semantic_search`, `grep_docs`) that produce valid paths. It also differentiates from siblings by directing users to `lookup_native` for script natives and `grep_docs` for code symbols, making the tool's unique role unmistakable.

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?

Explicit usage guidance is abundant: 'Use to retrieve full content after a search snippet looks promising' establishes the primary trigger, and alternatives are specified for natives (`lookup_native`) and code symbols (`grep_docs`). It even explains how to handle community findings (`learning:N` paths) and discouraged path shapes, leaving no ambiguity about when to invoke this tool.

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

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

With annotations declaring readOnlyHint=true, the description adds significant context beyond that: it discloses the tool is cheap and has no embedding, mentions the specific content covered (result modifiers, invokeNative vs invokeNativeByHash, type mapping, pointer-arg gotchas), and tells the user to call it only once per session. This goes well beyond the structured annotations.

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

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

The description is four sentences, each with a distinct purpose: purpose, usage timing, content scope, and cost/behavior. It is front-loaded with the core action and contains no redundant phrases 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 the tool has only one parameter and no output schema, the description provides comprehensive context: what it does, when to use it, why it's needed, what it covers, and its low cost. It fully prepares 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?

The schema covers the only parameter (language) with a clear enum and description, so the baseline is 3. The description mentions 'in `js` or `lua`' which mirrors the enum but doesn't add new semantic details beyond what the schema already provides.

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

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

The description clearly states the tool loads a 'calling-convention reference for RedM/RDR3 natives' in a specific language, which is a specific verb+resource. It distinguishes itself from sibling tools like lookup_native or get_document by emphasizing that it is the translation guide for JS/Lua authors, addressing a unique gap in the documentation.

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

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

The description explicitly says 'Call ONCE per session before writing native-calling code', providing clear when-to-use guidance. It explains why this tool is needed (every native doc page only shows Lua examples) but does not explicitly name alternatives or say when not to use it, so it doesn't reach 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?

Beyond the readOnlyHint annotation, the description discloses return format (matched lines with path + line number), ±60 char windowing for long lines, and the fact that read_lines is needed for mega-tables because get_document only holds the ~80-line head. It also explains the prior_attempt retry mechanism. No contradiction with annotations.

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

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

The description is long but every sentence earns its place. It is front-loaded with the core purpose, then exclusions, parameter tips, return behavior, and fallback guidance. There is no repetition of schema fields and no irrelevant content.

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

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

The description covers all critical operational aspects: scope, exclusions, mandatory use cases, parameter hints, return format, windowing, how to read around hits, and retry behavior. For a complex tool with no output schema, this fully equips the agent to use it 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?

Although schema coverage is 90%, the description adds strategic meaning: contextBefore/contextAfter saves a follow-up get_document call, filesOnly is cheap exploration, multiline enables cross-line patterns, and prior_attempt is for retries. It also provides concrete pattern examples that make parameter usage intuitive.

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

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

The description opens with a specific verb and resource: 'Find an EXACT literal token in raw doc files (markdown + lua).' It lists concrete examples (weapon_ped_ names, hashes, walkstyles) and explicitly contrasts with semantic_search and lookup_native, making its distinct purpose immediately obvious.

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

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

The description gives explicit when-to-use guidance (specific known strings) and when-not-to-use (behavior/concept queries -> semantic_search; script-native hash/name -> lookup_native). It also warns that semantic_search will miss tokens in the largest data tables and that grep_docs is REQUIRED there. The PREFER one-targeted-call guidance over alternations further steers 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?

Annotations already declare readOnlyHint=true, so no contradiction. The description adds useful behavioral context by clarifying it is not a content search and listing the exact categories and subcategories, which helps the agent understand what the tool will actually return. For a simple read-only listing tool, 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 concise and front-loaded with the main purpose in the first sentence. The subsequent sentences provide necessary usage guidance and category details without wasted words. Every sentence serves a clear purpose, and the list of categories is well-structured with parentheses for subcategories.

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 list tool with an output schema and read-only annotation, the description fully covers what the tool does, when to use it, and what the input means. The output schema handles return-value documentation, so no further description is needed here.

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 an enum for the optional category parameter, but the description adds meaning by explaining the categories and giving examples of subcategories (e.g., discoveries includes AI, weapons, peds). This goes beyond the raw schema and helps the agent choose an appropriate category value.

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

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

The description clearly states it lists doc categories and their namespaces, using the specific verb 'list' with a defined resource. It also distinguishes itself from sibling tools by explicitly saying 'NOT a content search' and positioning itself as an orientation tool before browse/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?

It gives explicit usage context: 'Use once at session start (or when unsure) before applying a category= / namespace= filter to browse / semantic_search.' This tells the agent when to use it and implies when not to use it (not as a content search). It also provides the category list for reference.

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 goes well beyond the readOnlyHint annotation by disclosing the return structure (findings[], refDocs[]), the behavior for large tables (inline content vs fetch), and the matching algorithm (exact first, ILIKE substring fallback). It explains how to chain with get_document for findings, adding contextual guidance not visible in the schema or annotations.

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

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

The description is long but well-structured. It is front-loaded with purpose and usage, then systematically details return values and special cases. The later details on refDocs and findings are essential for correct invocation, earning their place. A slight trim could improve conciseness, but the organization is clear.

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 an output schema available, the description still adds substantial context: it enumerates every return field (name, hash, namespace, return type, params, etc.), explains how to interpret refDocs inline vs fetch, and shows how to follow findings for deeper investigation. This is complete for the tool's complexity, and no crucial behavior is omitted.

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 already covers 75% of parameters, and the description adds meaningful detail: it notes case-insensitivity and optional 0x for hash, and clarifies the fallback behavior ('ILIKE substring') that is only implied in the schema. However, the 'limit' parameter is not described, though its min/max/default are in 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 purpose: 'Resolve a RedM/RDR3 SCRIPT native by hash or name'. It distinguishes from siblings by explicitly excluding game-data hashes and directing to 'grep_docs'. The specific verb 'Resolve' plus resource 'native' makes the scope 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 gives explicit usage triggers: 'Use whenever you see Citizen.InvokeNative(0x...), Citizen.invokeNative('0x...'), GetHashKey('NAME'), or a SCREAMING_SNAKE_CASE native name'. It also provides a clear when-not-to-use with alternative: 'NOT for game-data hashes (weapon/ped/animation names) — use grep_docs'. This fully addresses selecting between 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?

Annotations already indicate readOnlyHint=true, but the description adds valuable behavioral context: 1-based inclusive lines, 50-line default window, 400-line cap, and the indexing limitation that semantic_search/get_document cannot reach full table bodies. This goes beyond what annotations provide and helps the agent predict 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 dense but every sentence is purposeful. It front-loads the primary purpose, then adds usage context, limitations, and alternatives without any 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?

Despite lacking an output schema, the description covers trigger conditions, why this tool exists, parameter behavior, limits, and alternatives. It is sufficiently complete for an agent to select and invoke the tool correctly in the intended scenarios.

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

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

Schema coverage is 100% and the input schema already describes all parameters, including 1-based/inclusive semantics and the 400-line cap. The description mostly restates these details (e.g., 'omit end for a 50-line window') rather than adding new parameter-level meaning, so a baseline 3 is appropriate.

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

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

The description uses a specific verb+resource: 'Read an exact line range from a raw doc file by absolute line number.' It clearly distinguishes itself from siblings by being the 'windowed-read companion to grep_docs' and the ONLY way to read around hits in large data tables, making its purpose unmistakable.

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

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

The description gives explicit when-to-use guidance: call read_lines when grep_docs returns a hit, and states it is the only way for certain large tables. It also names alternatives for other cases: get_document for prose .md files, grep_docs for searching values, and lookup_native for script natives.

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

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

Annotations are minimal (readOnlyHint=true, openWorldHint=false). The description goes far beyond them by disclosing hybrid mode mechanics (RRF over vector + BM25), the exact result format (path, breadcrumb, heading, snippet, score), default merging of community findings, mode-specific behavior (semantic vs lexical), and the special `prior_attempt` server behavior for retries. No annotation contradiction; this is fully transparent.

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

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

The description is lengthy but every sentence carries critical information: purpose, alternatives, mode semantics, output format, follow-up action, filters, and retry behavior. It is front-loaded with the purpose statement and structured with clear operational details. Given the tool's complexity (7 parameters, multiple modes, nested objects), the length is appropriate and not padded.

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?

This is a read-only search tool with no output schema, so the description must carry the full burden of explaining return values and behavior. It states exactly what is returned (ranked snippets with path, breadcrumb, heading, snippet, score), how to retrieve full content, how modes differ, how filters work, and the `prior_attempt` improvement mechanism. It is fully complete for the tool's complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful semantic context beyond the schema: it explains what 'hybrid' means with concrete examples, clarifies the effect of `category=learnings`, and defines when to use `prior_attempt`. It does not explicitly discuss `limit`, `namespace`, or `responseFormat`, but these are already well-documented in the schema. Thus it adds genuine value above the structured fields.

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

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

The description opens with a specific verb+resource+scope: 'Search RedM/RDR3 docs by behavior, concept, OR exact token.' It also distinguishes itself from siblings by explicitly naming when to use `lookup_native` (specific native hash/name) and `grep_docs` (known asset names in large data tables). This is a model of purpose 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?

The description gives explicit when-to-use instructions: 'Use when you don't have a specific native hash/name (use `lookup_native`) and the term isn't a known asset name in a large data table (use `grep_docs`).' It also tells the agent to call `get_document` for full content and explains when to populate `prior_attempt` (after a failed search). This fully covers usage context and 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?

The description explains behavioral consequences beyond annotations: findings are merged into default `semantic_search` results, and `category: 'learnings'` filters to only findings. It also sets quality expectations (only verified findings, general to RedM/RDR3), which aren't in the annotations. The annotations (readOnlyHint=false) are consistent with the 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 lengthier than average but well organized into a main summary and bulleted lists for when/not-to-use. Every section contributes actionable guidance, and the explicit 'WHEN' structure improves scannability.

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 no output schema, so return-value explanation isn't needed. The description covers the 'why', 'when', 'when not', and behavioral effects (findings integrated into semantic search), making it sufficient for an agent to decide when to invoke it and how to write appropriate content.

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 already provides full descriptions for all five parameters (100% coverage), including 'Short, searchable summary' for title and 'Markdown explaining WHY' for body. The description adds little extra about parameters beyond restating those schema cues, so it relies on schema for field semantics.

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

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

The description clearly states the tool's purpose: sharing a verified finding back to the docs corpus. It uses specific verbs ('Share', 'record') and distinguishes from sibling read/search tools by emphasizing this is a write action. The phrase 'so the next agent can find it' makes the goal 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 includes explicit 'WHEN to use' and 'WHEN NOT to use' sections, listing concrete scenarios (burning iterations, undocumented quirks) and exclusions (info already in docs, guessing, project-specific content). It even names alternatives (`semantic_search`/`grep_docs`) for verifying prior existence, which serves as a when-not-to-use.

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