Santismm Knowledge — Harness Engineering & Agentic AI

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

With no annotations, the description carries the burden of behavior disclosure. It lists the included sections, which is useful, but it does not explicitly state read-only behavior, error handling (e.g., unknown slug), authentication needs, or whether the full architecture is always returned. This is acceptable for a simple getter but leaves some behavioral gaps.

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

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

The description is a single, well-structured sentence. It front-loads the verb and resource, provides the retrieval method, and parenthetically lists the contained elements. There is no wasted wording, and every element contributes to understanding.

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 (2 params, one required) and has an output schema, so return values are already structured. The description adds the major content sections. It does not discuss edge cases like missing slugs or locale behavior, but those are minor given the output schema and straightforward nature of the tool. It is sufficiently complete for effective use.

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

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

Schema description coverage is 100%: both 'slug' and 'locale' are described in the schema with examples and defaults. The description only reiterates that retrieval is by slug, adding no new meaning beyond the schema. Baseline 3 is appropriate since the schema fully documents the parameters.

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

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

The description uses a specific verb ('Get'), a specific resource ('one reference architecture'), and a retrieval key ('by slug'). It also enumerates the contents (request flow, reference scenario, KPIs, cost & scaling, patterns/knowledge), making it clearly distinct from sibling getters like get_pattern or get_governance.

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 clearly implies the use case: retrieve a single architecture when you know its slug. It doesn't explicitly state when not to use it or mention alternatives like list_architectures or search, but the sibling tool names provide that context, and the 'by slug' condition is a clear cue for when this tool 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, the description carries the full burden. It does disclose key behavioral context by listing what the response includes (scope, requirements, controls, checklist, pitfalls). However, it does not mention behavior on missing slugs, locale default handling, or potential response variations, leaving some transparency gaps.

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

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

The description is a single concise sentence with no filler. It front-loads the main purpose and enumerates included content efficiently, making every word earn 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 this is a simple get-by-slug tool with a complete schema and an output schema, the description is nearly sufficient. It clearly explains what the tool returns, and the output schema covers return structure. A brief mention of locale behavior or not-found handling would make it fully complete, but the current level is adequate for selection and invocation.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds no parameter-specific detail but matches the 'slug' parameter with 'by slug'. This meets the baseline for schema-heavy parameter documentation but adds no extra semantic value.

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

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

The description uses a specific verb ('Get') and resource ('AI governance unit'), identifies the lookup mechanism ('by slug'), and lists what the returned unit includes. It clearly distinguishes itself from list_governance and other sibling tools that list or retrieve different entity types.

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 clearly implies usage when you need a single governance unit by slug, and the mention of included content helps decide if this is the right tool. It does not explicitly contrast with alternatives like list_governance or search, but the 'by slug' qualifier provides clear context for the primary use case.

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

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

With no annotations provided, the description carries the full burden. It discloses the return payload (full Markdown body, provenance, related ids) and the lookup method. This is adequate for a read operation, though it doesn't explicitly state read-only status or permission requirements.

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

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

The description is two sentences, front-loaded with the core purpose, and contains no unnecessary words. It efficiently conveys the essential information.

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

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

Given the simple input (2 params, 1 required) and the presence of an output schema, the description covers the necessary selection and invocation details. It mentions the return content and lookup method, so the tool is fully understandable.

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 a small example ('HRN-001') but otherwise repeats schema information. It doesn't add significant meaning beyond the input schema.

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

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

The description clearly states the verb ('Get'), the resource ('one Harness Engineering Handbook chapter'), and the lookup method (by id or slug). It also specifies the return type (Markdown body, provenance, related ids), distinguishing it from sibling tools like get_architecture or get_pattern.

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 clearly scopes usage to handbook chapters, implying when to use this tool (when a specific chapter is needed). It doesn't explicitly mention alternatives like list_handbook or other get_* tools, but the context is clear enough to avoid confusion.

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 transparency burden. It clearly discloses the conditional return behavior: full entry by default, single-locale body if locale is provided. This is useful, though it does not address error handling or edge cases.

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 wasted words. It perfectly balances brevity and information.

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

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

The tool is simple, and the description covers the core behavior. An output schema exists to explain return values. The only gap is the inconsistency with the schema's locale default, which prevents full completeness.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful distinction between 'full entry' and 'single-locale body', clarifying the locale parameter's effect. However, this conflicts with the schema's stated default of 'en' for locale, which may confuse agents.

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 knowledge unit by slug, using a specific verb and resource. It does not explicitly differentiate from sibling tools like list_knowledge or get_architecture, but the resource type is unambiguous.

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

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

Usage context is implied: you would use this when you know the slug and want one specific knowledge unit. No explicit alternatives, exclusions, or when-not-to-use guidance is provided, so it falls short of a higher score.

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 disclosure. It reveals the scope of the response (every domain, categories, tool mappings, identifiers, languages, licence, and bulk-ingest URLs) and assures the user that one call is sufficient. This is adequate for a non-mutating overview tool, though it does not mention potential limitations like output size or formatting.

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 and front-loaded with the key instruction 'Get the corpus map — start here.' Every clause adds specific information about the domains and metadata returned, with 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?

Given the empty input schema and zero parameters, the description fully covers when to use the tool and what to expect. It complements the output schema by detailing the domains, categories, tool mappings, identifiers, languages, licence, and URLs, making the tool's purpose and value complete.

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

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

The tool has zero parameters, which per the rubric warrants a baseline score of 4. The description does not need to explain parameters and instead focuses on what the output contains, which is appropriate for a parameterless tool.

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 identifies the tool as returning the corpus map and explicitly says to start here, which distinguishes it from the domain-specific sibling tools like get_architecture and get_knowledge. It names the covered domains and the kind of information returned, 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 states 'start here' and 'One call is enough to know exactly where to go next', providing clear context that this is the entry point before using other tools. It does not explicitly list when not to use it, but the guidance is strong enough for a zero-parameter overview 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?

No annotations are provided, so the description carries the full burden. It discloses what the response includes (problem, solution, KPIs, failure modes, lessons), but does not address error behavior for missing slugs or locale effects (though locale is in schema). This is adequate but not rich.

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

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

One sentence with the main purpose front-loaded and a parenthetical listing contents; zero waste and highly scannable.

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?

Simple tool with 2 params and an output schema present; description states what it returns and how to identify the pattern. No critical gaps exist for invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description only reiterates slug-based lookup and adds no extra meaning beyond what the schema already provides for the parameters.

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

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

Description clearly states 'Get one Enterprise AI pattern by slug' specifying the verb, resource, and identification mechanism. It distinguishes from sibling list_patterns (which enumerates) and other get_* tools by focusing specifically on 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?

Implies usage for retrieving a single pattern when the slug is known, with a clear context. It does not explicitly mention alternatives like list_patterns or search, but the clarity of 'one ... by slug' provides adequate 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool returns both outgoing and incoming neighbours and includes the relationship type, which are essential behavioral traits. It does not mention pagination or depth limits, but the concept of 'neighbours' implies direct connections, and the output schema covers return structure.

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 that front-loads the action ('Traverse the knowledge graph') and immediately defines the output. Every clause adds value, with no wasted words.

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

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

Given the moderate complexity of bidirectional graph traversal and the presence of an output schema, the description is sufficiently complete. It explains the core behavior and distinguishes itself from sibling tools. It does not address potential edge cases like cycles or disconnected nodes, but these are likely covered by the output schema or are not essential for initial tool selection.

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 describes slug and locale explicitly (67% coverage), and the description adds context by framing the unit as the starting point in the graph. However, it does not explain the 'domain' parameter beyond what the enum lists, nor does it detail how slug and domain interact. The description adds some meaning but does not fully compensate for the missing domain description.

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

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

The description clearly states a specific verb ('traverse') and resource ('knowledge graph'), and explicitly defines the output: neighbours via outgoing and incoming links with relationship types. This distinguishes it from sibling tools that fetch single units (e.g., get_knowledge, get_pattern).

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

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

The description provides clear context: use this when you need to explore relationships from a starting unit. It does not explicitly mention alternatives or exclusions, but the unique traversal purpose is obvious compared to the sibling 'get_*' tools, making the usage context 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?

With no annotations provided, the description carries the full burden for behavioral disclosure. It adds useful context by listing the output fields and stating it returns all architectures, but it does not mention read-only behavior, pagination, authentication, or any potential side effects. While a 'list' operation is inherently non-destructive, explicit disclosure of these traits would enhance 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 a single, well-structured sentence that front-loads the action ('List all reference architectures') and then specifies the returned fields. The parenthetical clarification adds value without verbosity. Every word earns its place, achieving maximum conciseness.

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

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

Given the tool's simplicity (one optional parameter, read-only list operation) and the presence of both an input schema and output schema, the description provides sufficient context. It clearly names the resource, the scope ('all'), and the exact fields returned. No critical information is missing for an agent 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?

The schema covers the only parameter (locale) with a complete description and default value, so schema coverage is 100%. The description adds no additional parameter information, so the baseline score of 3 applies. The description focuses on output rather than input 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 lists all reference architectures and specifies the exact fields returned (id, slug, category, name, summary, provenance). The verb 'List' is specific and the resource is unmistakable, distinguishing it from sibling tools like get_architecture (which fetches a single item) and other list_* tools for different content types.

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

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

The description provides clear context for when to use the tool: to obtain a complete list of reference architectures. It implicitly differentiates from get_architecture, but does not explicitly name alternatives or exclude other tools. There are no prerequisites or filtering instructions, so the usage is straightforward and well-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 provided, the description carries the burden of behavioral disclosure. It does add value by specifying the output fields and the scope of governance units, and it implies a read-only operation via 'List'. However, it does not mention pagination, sorting, or any side effects, leaving some transparency gaps.

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

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

The description is a single sentence that starts with the verb and resource, then enriches with category examples and output fields. Every phrase conveys useful information with no redundancy or filler, 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?

The tool is simple, with one optional parameter and an output schema. The description covers the entity types and output fields adequately. It could mention pagination or sorting, but for a straightforward list tool with an output schema, the description is nearly complete, earning a 4.

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 input schema, including allowed values and default, so schema coverage is 100%. The description does not mention the parameter, but since the schema fully explains it, no compensation is needed. 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 the action ('List all AI governance units') and specifies the resource with concrete categories and examples. It distinguishes from sibling tools like get_governance (which would fetch a single unit) and other list_* tools (which target different entity types), 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 when to use the tool (when you need a complete list of governance units), but it does not explicitly mention alternatives or exclusions. No guidance is given about using get_governance for specific units or other list tools for different categories, so usage context is clear but not fully elaborated.

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

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

No annotations are provided, so the description carries the transparency burden. It identifies the operation as a list (implying read-only) and adds context about the handbook's contents, but does not describe return format, pagination, or any other behavioral nuances beyond what the name conveys.

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, somewhat dense sentence that front-loads the core purpose. The enumeration of topics is informative but slightly long; however, every element adds value in clarifying the handbook's scope.

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

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

The tool is simple with one optional parameter and an output schema available. The description sufficiently explains what the tool lists, and the output schema handles return value details, so the description is complete for the tool's complexity.

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

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

The schema fully describes the single locale parameter with an enum, default, and description. The description adds no additional parameter semantics, but schema coverage is 100%, so the baseline 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 opens with a specific verb and resource: 'List the Harness Engineering Handbook chapters'. It clearly distinguishes from siblings like get_handbook (retrieve a chapter) and list_knowledge (list knowledge resources) by focusing on the canonical handbook and enumerating its content areas.

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 clearly implies usage: use this tool when you need a listing of the handbook's chapters. It does not explicitly mention alternatives or exclusions, but the context is unambiguous given the sibling tool names and the direct statement of purpose.

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

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

With no annotations, the description must carry full behavioral burden. It discloses the return fields and that it lists all units, but omits details like whether authentication is required, pagination behavior, or read-only guarantees. The 'List' verb implies a read operation, but more explicit disclosure would be better.

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 that wastes no words. It states the action, resource, scope, and return fields efficiently.

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 provides sufficient scope and return information. It could mention locale awareness or pagination, but the schema and simplicity cover most needs.

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 the single 'locale' parameter clearly defined in the schema (enum and default). The description adds no parameter details, but the schema fully handles it, so 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 clearly states the tool lists all knowledge units with specific fields (slug, category, title, summary, provenance). It distinguishes from sibling tools like list_architectures and get_knowledge by naming the exact resource and scope.

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

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

The description implies use when you want to enumerate all knowledge units, but it does not explicitly contrast with get_knowledge or list alternative tools. No when-not-to-use guidance is provided.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It states that the tool lists all patterns, which implies a read-only operation, but does not disclose pagination behavior, locale effects, or any limitations or side effects. Additional context about the absence of filters or the completeness of the list would improve 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 a single, front-loaded sentence that directly states the action (list), resource (patterns), and return fields. Every word earns its place, with no unnecessary details or repetition.

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

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

For a simple list tool with an output schema and a single optional locale parameter, the description is complete. It specifies the resource being listed and the fields returned, which is sufficient for an agent to understand the tool's purpose and select it over siblings like list_architectures.

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 fully describes the single optional locale parameter with an enum and description, achieving 100% schema coverage. The description does not add parameter details, but none are needed beyond the schema, so the baseline score 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 uses a specific verb 'List' with a specific resource 'Enterprise AI patterns' and enumerates the fields returned (slug, category, name, summary, provenance). It clearly distinguishes this tool from sibling list_* tools by naming the resource type and clarifying it refers to reusable agentic design 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 clearly indicates this tool is for listing all patterns, providing clear context for when to use it. However, it does not explicitly mention alternatives or when not to use it (e.g., for retrieving a single pattern), so it lacks explicit exclusions.

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

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

With no annotations, the description carries the full behavioral burden and does well: it reveals ranking, cross-language matching, accent insensitivity, and that each hit includes a relevance score and matched fields. It doesn't mention potential side effects (likely none) or pagination behavior, but the schema covers limit. The disclosed traits exceed the baseline.

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 primary purpose, then provides scope, usage guidance, and result detail. Every phrase adds value; 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 the tool's complexity (multiple domains, params, output schema) and the presence of an output schema, the description is quite complete. It explains what results contain, how to proceed to detail, and the corpus scope. It could additionally mention domain restriction via parameter, but that is already in the schema. Overall adequate for agent selection and invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds marginal value by clarifying accent-insensitivity and multi-language matching, which relates to the query parameter, but it does not add substantial syntax or format 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 a specific verb ('search'), a specific resource ('the whole corpus'), and gives the exact scope ('knowledge, patterns, architectures, governance and the handbook'). It also distinguishes itself from the get_* and list_* siblings by emphasizing ranked keyword search and follow-up via get_* tools.

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

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

The description explicitly gives a usage pattern: use search to find items, then 'follow up with the matching get_* tool for full detail.' It also advises querying in the user's own words and notes language/accent handling. However, it does not explicitly mention when to use list_* tools instead, so it falls short of fully explicit when-not/alternatives.

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