Santismm Knowledge — Harness Engineering, Agentic AI & Governance

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral context by disclosing the response structure and the requirement of a prior slug lookup, which goes beyond the annotations without contradicting them.

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 concise sentences: first packs the purpose and content, second gives the usage prerequisite. Zero redundancy, front-loaded, and 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?

For a simple retrieval tool with 2 params and an output schema, the description covers purpose, content, and usage flow. It fully equips the agent to select and invoke the tool correctly, especially with sibling context showing distinct resources.

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%—both `slug` and `locale` are well documented in the schema. The description adds minimal parameter-specific value beyond restating 'by slug' and the flow context. Baseline 3 is appropriate given the schema's thoroughness.

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 a single reference architecture by slug and enumerates the included content (request flow, reference scenario, KPIs, cost & scaling, patterns/knowledge). It distinguishes from sibling list/search tools by specifying the unique resource and identifier.

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 explicitly instructs to use this tool after obtaining a slug from `search` or `list_architectures`, providing practical usage context. It doesn't explicitly enumerate when-not-to-use alternatives, but the prerequisite guidance makes the usage scenario 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds beyond annotations by listing the response contents ('scope, key requirements, implementable controls, a checklist and common pitfalls'), giving the agent insight into what the tool returns. No contradictions.

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: the first states purpose and content, the second gives usage context. It is front-loaded with the main action and has zero wasted words. 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?

For a simple get-by-slug tool with an output schema, the description covers purpose, usage flow, and response contents. Combined with rich annotations and a complete output schema, the agent has everything needed to correctly select and invoke 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?

Schema description coverage is 100% with both parameters well-described (slug with example, locale with default). The description restates the slug concept but adds no new parameter semantics beyond the schema. Baseline 3 applies since schema does the heavy lifting.

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 'Get one AI governance unit by slug' with a specific verb and resource. It distinguishes from siblings like list_governance (list) and search by indicating this is the detail-fetch tool, and it enumerates the contents (scope, requirements, controls, checklist, pitfalls), making the tool's 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 explicitly says 'Use this once `search` or `list_governance` has given you a slug', providing clear when-to-use guidance. It names alternatives (search, list_governance) as prerequisites, effectively telling the agent to use those first, which is a strong usage guideline.

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, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable context on what is returned (full Markdown body, provenance, related ids) and clarifies that ids can be slugs or formatted ids, going beyond the schema. It does not contradict annotations and provides meaningful behavioral detail.

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, no wasted words. The action and target are front-loaded, followed by output details and a usage precondition. The structure is ideal for quick agent parsing.

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 read-only retrieval tool with an output schema, the description covers the necessary context: what it returns, how to obtain the id, and the parameter format. No essential operational detail is missing given the rich annotations and output schema.

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

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

The schema description covers both parameters fully (id format and locale enum with default). The description's mention of 'id or slug' mirrors the schema, adding no new information. With 100% schema coverage, the description does not need to compensate, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool retrieves a single Harness Engineering Handbook chapter by id or slug, distinguishing it from sibling get_* tools targeting other domains (architecture, governance, etc.). It also specifies the output (Markdown body, provenance, related ids), making the purpose specific and unambiguous.

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

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

The description explicitly instructs the agent to use this tool only after obtaining an id from 'search' or 'list_handbook', providing a clear precondition. This guides sequencing and implies when not to use the tool (when you lack an id). It effectively names the alternatives that precede it.

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 and idempotentHint=true, so the description needn't repeat safety traits. It adds value by explaining that it returns 'the full entry, or a single-locale body if locale is given', clarifying behavior beyond the schema. No contradiction.

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, with the primary purpose front-loaded ('Get one knowledge unit by slug'), followed by return behavior and usage guidance. Every clause is informative; no filler 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?

The output schema covers return details and annotations cover safety/idempotence, so the description only needs to handle purpose and usage—which it does thoroughly. No significant gaps for a read-only retrieval 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?

Both parameters have full descriptions in the schema (100% coverage), so the description adds minimal new parameter semantics. It references slug and locale contextually but doesn't go beyond schema definitions. 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 clearly states 'Get one knowledge unit by slug', naming the specific resource and operation. It explicitly contrasts with siblings like `search` and `list_knowledge` by indicating it retrieves a single known unit rather than discovering slugs.

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 when-to-use guidance: 'Use this once `search` or `list_knowledge` has given you a slug.' This tells the agent the correct sequence and implies which tools to use instead for discovery. 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context about the return content (domains, categories, tool identifiers, bulk-ingest URLs) and confirms the read-only nature, but does not contradict annotations. It also notes that one call is sufficient, which is a useful behavioral trait.

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 'start here' and is only two sentences long. The second sentence is somewhat dense with enumerated content, but every detail serves a purpose. It is concise and well-organized for the information it conveys.

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 no parameters and an existing output schema, the description covers everything an agent needs: what the output contains, how it aids navigation, and that it is the starting point. It is fully complete for an overview tool of this 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?

The input schema has zero parameters, so there are no parameter semantics to clarify. Per the baseline for 0 params, a score of 4 is appropriate; the description cannot add more meaning to parameters that don't exist.

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: 'Get the corpus map — start here.' It details exactly what it returns (every domain, categories, tool mappings, identifiers, languages, licence, bulk-ingest URLs), making its role as a navigational overview distinct from sibling tools like get_knowledge or list_patterns.

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 'start here' and 'One call is enough to know exactly where to go next,' indicating this tool should be used first to orient and guide subsequent tool selection. However, it does not explicitly name alternatives or state when-not-to-use, so it falls just short of full 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds that the response includes specific sections (problem, solution, KPIs, failure modes, lessons), which is helpful but is more about return content than behavior. It does not contradict 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?

Two sentences: the first states the purpose and content, the second gives a clear usage precondition. Every word earns its place; 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 the tool's simplicity, the presence of a comprehensive output schema, and strong annotations, the description covers all necessary context. It explains what the tool returns and when to use it, making it complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, with both 'slug' and 'locale' already well described. The description mentions 'by slug' but the schema already explains that clearly, so the description adds no new parameter meaning beyond what the schema provides. Baseline 3 applies.

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 ('Get') and resource ('Enterprise AI pattern') with a clear identifier ('by slug'). It also lists the content areas (problem, solution, KPIs, failure modes, lessons), which distinguishes it from sibling tools like get_architecture or get_governance that 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 explicitly tells the agent when to use this tool: 'Use this once search or list_patterns has given you a slug.' This gives a clear workflow context and distinguishes it from the search/list siblings, which are for discovery rather than retrieval.

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, idempotentHint, and destructiveHint, covering the safety profile. The description adds behavioral detail beyond that: it returns both outgoing and incoming links, each with a relationship type, and frames it as a traversal following a prior get_* call. No contradictions with annotations, and the added context is valuable without being excessive.

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-loaded to state the core action and output, and the second giving a brief usage directive. Every word is useful, with no redundancy or repetition of schema/annotation content. This is a model of concise, structured description.

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 read-only graph traversal tool with an output schema, annotations, and a clear description, this is complete. It explains what it does, when to use it, and what it returns. The output schema presumably documents the specific response shape, so the description doesn't need to elaborate. No critical information is missing.

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 67%, with slug and locale already described. The domain parameter has an enum but no description; the description does not clarify its meaning beyond 'unit' and the schema's enum values. The description's mention of 'given a unit' aligns with slug/domain but doesn't add further semantic detail. Since the schema covers most parameters, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Traverse the knowledge graph' and specifies it returns neighbours (outgoing and incoming links) with relationship types. This distinguishes it from sibling get_* tools that fetch a single unit and search/list tools that find or enumerate units. The verb 'traverse' plus the explicit output details make 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 gives explicit usage context: 'Use this after a `get_*` call to widen an answer with adjacent units.' This tells the agent when to invoke it, but it doesn't explicitly mention alternatives or when not to use it. Since the sibling tools are clear from the description, the guidance is adequate but could be more exclusionary.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no additional behavioral traits beyond what annotations provide, such as pagination or ordering. It is consistent with annotations, so no contradiction.

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 zero filler. It front-loads the core action ('List all reference architectures'), then adds scope, returned fields, and a usage pointer. 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?

Given the tool has an output schema (covering return structure), one optional parameter, and strong annotations, the description fully covers what the tool does, when to use it, and how it differs from `search`. No gaps remain for effective 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?

The sole parameter (locale) has full schema coverage: an enum (en/es/pt) and a description. The description adds no extra meaning for parameters, so the baseline of 3 applies where the schema does the heavy lifting.

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 all reference architectures' with a specific verb and resource, and enumerates the fields returned (id, slug, category, name, summary, provenance). It explicitly distinguishes from the sibling `search` tool by noting it's for browsing when you have a name, not a use case.

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 when to use this tool ('Use this to browse the blueprints') and names the alternative ('use `search` when you have a use case rather than a name'). This gives clear guidance on tool selection versus a sibling, exceeding basic 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?

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false). The description adds some context about the scope of governance units but does not disclose additional behavioral traits such as pagination, rate limits, or error behavior. Since the bar is lowered with annotations present, the added value is moderate.

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, well-structured sentence with parenthetical examples and an explicit alternative clause. It is front-loaded with the core action and resource, and every element adds value without redundancy.

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

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

For a simple list tool with one optional parameter and an output schema, the description adequately covers purpose, usage, and return fields. It is complete enough for an agent to invoke correctly without ambiguity.

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 only parameter `locale` is fully described in the schema (enum with default and description), so schema coverage is 100%. The tool description does not add parameter-specific details, but the baseline of 3 applies because the schema does the heavy lifting.

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

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

The description states a specific verb ('List') and resource ('AI governance units') with concrete examples (EU AI Act, ISO 42001, NIST AI RMF), and enumerates the output fields (id, slug, category, name, summary). It clearly distinguishes from sibling `search` by naming it as an alternative for obligations/controls.

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 guidance: 'Use this to browse the regulations and standards; use `search` for an obligation or control.' This tells the agent when to choose this tool versus a sibling, and the phrase 'List all' implies no filtering is needed.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds contextual scope (the handbook corpus) but no further behavioral traits such as ordering, pagination, or authentication requirements. It neither contradicts nor significantly extends beyond the 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 two sentences long, with the main action and scope in the first sentence and usage guidance in the second. Every sentence earns its place, and the key information is front-loaded.

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

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

For a simple list tool with zero required parameters and an output schema present, the description fully covers what the tool does, what the list contains, and when to use it. No critical information is missing.

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

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

Schema description coverage is 100% for the single optional 'locale' parameter, which includes an enum and description. The tool description adds no additional parameter semantics, so the schema carries the full burden; 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 begins with a specific verb+resource: 'List the Harness Engineering Handbook chapters (HRN-001…)', and expands with a detailed enumeration of the corpus content. It clearly distinguishes from the sibling 'search' tool, stating the appropriate use case for each.

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 provided: 'Use this to see the chapter map; use `search` when you have a topic rather than a chapter.' This directly tells the agent when to prefer this tool over the alternative.

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 cover read-only and idempotent behavior, lowering the burden. The description adds that the tool returns 'all' knowledge units and lists the included fields, which helps set expectations for the response beyond the 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?

Two sentences, first front-loads the core function, second provides usage guidance. 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?

With an output schema present and good annotations, the description covers purpose, usage, and alternatives. It also includes the provenance aspect which is a likely key differentiator for this 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 single `locale` parameter is fully described in the input schema (coverage 100%) including its enum values and default. The description adds no additional parameter semantics, so the baseline of 3 applies.

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

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

The description states a specific action and resource: 'List all knowledge units (concepts on agentic & enterprise AI) with slug, category, title, summary and Evidence-First provenance.' It clearly distinguishes this from the 'search' sibling by positioning it as a browsing tool, 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?

'Use this to browse the domain; use `search` when you have a question rather than a slug' explicitly states when to use this tool and when to use an alternative. This is textbook 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral context by specifying the exact return fields and that it lists ALL patterns, which goes beyond the annotations. No contradictions.

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 action and output fields, followed by succinct usage guidance. Every word adds value with no unnecessary fluff.

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

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

Given the simplicity of the tool (list operation, one optional parameter), the comprehensive annotations, and the presence of an output schema, the description fully covers the essential context. It includes the purpose, output fields, and usage alternatives, leaving no critical 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 schema description for the sole parameter 'locale' is complete (100% coverage) with a clear description and enum values. The tool description adds no extra meaning to the parameter, so the baseline of 3 is appropriate.

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

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

The description clearly states the action (List), the resource (Enterprise AI patterns), and the output fields (slug, category, name, summary, provenance). It distinguishes itself from sibling tools by explicitly contrasting with `search` and positioning itself as a catalogue browsing 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 explicitly says when to use this tool ('Use this to browse the catalogue') and when to use the alternative (`use 'search' when you are looking for a pattern that solves a problem`). This provides clear usage guidance and differentiates from the most similar sibling.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds crucial behavior: ranking, language/accent insensitivity, and that hits carry relevance scores and matched fields. It also reveals the intended workflow of following up with get_* tools, going beyond annotations with no contradictions.

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?

Four sentences, each earning its place: main function, behavioral details, output characteristics, and usage directive. Information is front-loaded and no words are wasted.

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 output schema present and sibling tools listed, the description fully addresses intended use, follow-up actions, and distinctive features. It is self-sufficient for an agent to know when and how to invoke 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?

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning by noting 'ignores accents' and instructing to 'query in the user's own words,' which goes beyond the schema's language enum. It also clarifies domain scope with 'whole corpus,' slightly raising the score.

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 'Ranked keyword search across the whole corpus,' specifying the verb, resource, and scope. It explicitly distinguishes itself from sibling get_* and list_* tools by positioning itself as the search entry point, and it names the corpus domains it covers.

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?

Directly provides usage guidance: 'Use this before any `get_*` tool whenever you have a question rather than an identifier.' It also tells the user to 'follow up with the matching get_* tool for full detail,' making when-to-use and when-not-to-use explicit.

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