Read-only tools over the Safer Agentic AI framework: 238 patterns + 14 heuristics.
Scored across 12 tools
The set separates retrieval patterns well: get_* for single items, list_* for collections, plus reference navigation and stats. Minor confusion remains between find_patterns_for_task (semantic task routing) and search_patterns (keyword), and among list_requirements, list_unreviewed, and search_patterns which all return pattern sets, though descriptions distinguish them. Overall boundaries are clear.
Strong verb_noun convention throughout (get_requirement, list_suites, get_cross_references, search_patterns). Two outliers—resolve_id and review_stats—deviate from the verb_noun pattern but remain readable and unambiguous. Minor deviation only.
12 tools is well within the ideal 3-15 range for a knowledge-base server. Each tool covers a distinct retrieval need (orient, search, fetch, navigate, review) with no filler.
Retrieval and navigation are thoroughly covered (single-item gets, listed collections, cross/reverse references, id resolution, coverage stats, review queue). The review workflow implied by list_unreviewed has no corresponding tool to record or submit a review, and there is no get_suite detail beyond list_suites—minor gaps an agent can work around.
Given a natural-language task description (e.g., 'I'm building a tool-using agent that runs shell commands'), return the most relevant patterns grouped by suite. Use this as a starting point for any cross-cutting design question; then follow up with get_requirement on specific pattern_ids. Defaults to verbosity='compact' (cheap triage); pass 'full' to inline snippets and confidence flags.
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | ||
| limit | No | ||
| verbosity | No | compact |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds genuine value beyond that: results are grouped by suite, defaults to cheap compact triage, and 'full' inlines snippets and confidence flags. It does not disclose result volume, ordering, or what happens on zero matches.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly packed sentences, front-loaded with the core purpose, then when-to-use, then the verbosity default that matters most for cost. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does the work of explaining the return shape (patterns grouped by suite; snippets and confidence flags in full mode) and the intended workflow. Minor gap: limit semantics and the behavior at low/zero relevance are unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the full burden. It explains verbosity well (compact = cheap triage, full = inline snippets and confidence flags), but says nothing about the limit parameter's role or default, and only implicitly characterizes task via the example.
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 and resource ('return the most relevant patterns grouped by suite') from a natural-language task, and it contrasts its role with get_requirement as the follow-up tool. It does not distinguish itself from the similarly-named sibling search_patterns, so an agent can't tell those two apart from the text alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly positions itself as 'a starting point for any cross-cutting design question' with a clear follow-up path via get_requirement on specific pattern_ids. It stops short of naming search_patterns or stating when this tool should NOT be used instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return outgoing adjacencies for a pattern. explicit_cross_references are author-asserted (each pattern's cross_references YAML field). inferred_adjacent (when include_inferred=true) currently returns same-suite siblings only — it does not do semantic similarity. Treat inferred entries as 'neighbours worth scanning,' not as endorsed dependencies.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| include_inferred | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds genuine behavioral disclosure beyond them: it explains what explicit_cross_references are sourced from, and that inferred_adjacent is currently limited to same-suite siblings rather than semantic similarity. That limitation is exactly the kind of non-obvious caveat an agent would otherwise get wrong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the purpose and followed immediately by the field semantics and the caveat. No filler or restatement of the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read-only tool with no output schema, the description effectively documents the return shape by naming explicit_cross_references and inferred_adjacent and explaining their provenance. It stops short of covering error behavior for an invalid id or what an empty result means, but the core call path is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden. It explains include_inferred well (its effect and its current limitation), which is the more confusing of the two parameters, but the required `id` parameter is never defined — the agent must infer from "for a pattern" that it is a pattern identifier.
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 and resource ("Return outgoing adjacencies for a pattern") and even names the two returned collections. The word "outgoing" implicitly separates it from the sibling get_reverse_references, but that tool is never named, so the differentiation must be inferred.
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 real interpretive guidance for the output ("Treat inferred entries as 'neighbours worth scanning,' not as endorsed dependencies") and ties include_inferred to the inferred branch. However, it never states when to call this versus get_reverse_references or search_patterns, so the routing decision is left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single operational heuristic by id (e.g., 'OH::geoffrey-pattern'). Returns the full entry: principle, framework mapping, evidence sources from production deployment, design patterns, anti-patterns, and discovery narrative.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the safety profile is covered. The description adds genuine value by enumerating the return contents (principle, framework mapping, evidence sources, etc.), which matters since no output schema 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?
Two tightly packed sentences with the action and scope front-loaded, followed by the return payload. No filler; every clause carries 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?
For a get-by-id tool with no output schema, the description adequately covers both the input format and the returned fields. It does not mention not-found/error behavior, but with annotations covering the safety profile and a single simple parameter, this is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the single 'id' parameter. The embedded example ('OH::geoffrey-pattern') demonstrates the expected namespace-prefixed format, which is meaningful for correct invocation, though it doesn't explain length or validation limits.
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?
States a specific verb ('Retrieve'), resource ('operational heuristic'), and scope ('a single ... by id'), with a concrete id example ('OH::geoffrey-pattern'). The word 'single' implicitly distinguishes it from the sibling list_operational_heuristics, so an agent can route correctly without opening the schema.
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 'by id' scoping implies this is the lookup counterpart to list_operational_heuristics, but no explicit when-to-use/when-not guidance or prerequisites are given. Usage is only implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve one subgoal (framework normative content + Pattern layer guidance) by pattern_id (e.g., 'D3::idx2::sandboxing') or display_id (e.g., 'D3.2'). display_id may resolve to multiple subgoals — underlined variants share display_ids.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| include_pattern | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real behavioral context: what the record contains (normative content + Pattern guidance) and the non-obvious trait that a display_id can map to multiple subgoals because underlined variants share display_ids. It does not describe the shape of a multi-resolution result, which keeps it from a 5.
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 tight sentences with zero filler: the lookup key comes first, then the returned content, then the ambiguity caveat. Every clause carries information an agent needs.
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 output schema, the description correctly steps in to say what is returned (framework normative content + Pattern layer guidance), and annotations cover the read-only nature. The remaining gaps are the unexplained `include_pattern` toggle and what an ambiguous display_id resolution actually returns, which is a moderate but not fatal omission.
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 carry the parameter burden. It handles `id` well, giving both accepted formats and examples plus the ambiguity caveat, but `include_pattern` (default true) is never mentioned, leaving one of the two parameters undocumented everywhere. Partial compensation, not full.
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?
States a specific verb and resource ("Retrieve one subgoal") and defines the payload precisely as framework normative content plus Pattern layer guidance. The singular "one" contrasts implicitly with the sibling list_requirements, and the two example ID formats make the input model unambiguous. An agent can distinguish this from search_patterns or list_requirements without opening a schema.
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 is implied by accepting either a pattern_id or a display_id, and it appropriately warns that a display_id may resolve to multiple subgoals. However, it never states when to reach for this tool versus list_requirements, search_patterns, or resolve_id, nor what to do when the display_id is ambiguous. Adequate context, but no explicit when/when-not routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return patterns that reference the given pattern_id in their cross_references. Complement to get_cross_references (outgoing); this shows incoming. Use to find all consumers of a given pattern.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine semantic context by explaining the incoming-reference direction, but says nothing about return shape, result size, or whether unscoped queries are bounded.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short clauses, front-loaded with the core behavior. Slight redundancy: 'Complement to get_cross_references (outgoing); this shows incoming' and 'Use to find all consumers' partially restate the same directionality idea.
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 single-parameter, read-only lookup with no output schema, the description gives the agent enough to invoke it correctly. Return-format expectations are the only notable omission, and the annotations already cover the safety behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the parameter is only named 'id', but the description clarifies that the id identifies a pattern (referring to it as pattern_id), which is meaningful semantic information missing from the schema. It adds no format, example, or lookup guidance beyond that.
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?
States a specific verb and resource ('Return patterns that reference the given pattern_id in their cross_references') and explicitly distinguishes itself from the sibling get_cross_references. An agent can tell the direction of the relationship without opening either schema.
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?
Names the alternative tool (get_cross_references as 'outgoing') and states the selecting condition ('this shows incoming'), plus a concrete use case ('find all consumers of a given pattern'). The when-to-use decision is fully specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List operational heuristics distilled from production agentic AI deployment (Claude Code, Rewind). These are cross-cutting safety principles discovered through building and operating AI agents, mapped to framework suites. Optional filters: suite_id (heuristics relevant to a specific suite), query (keyword search across titles and principles). Separate from the normative pattern layer — different category of knowledge.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Keyword search across titles, principles, narratives | |
| suite_id | No | Filter by framework suite (e.g., 'D3', 'I2') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered without the description. The description adds useful content characterization (cross-cutting safety principles mapped to framework suites, drawn from real deployments) but says nothing about result volume, pagination, or ordering for a list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the resource and provenance before the filters, with no filler. The final sentence about the normative pattern layer is slightly tangential but earns its place as a disambiguation signal.
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, no-required-parameter list tool with a fully documented two-param schema, the description covers what the data is, where it comes from, and how to narrow it. The absence of any note on return shape or result size is a minor gap given there is no 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?
Schema description coverage is 100%, so the schema already documents both optional filters; baseline is 3. The description restates the filter intents and adds the example suite IDs ('D3', 'I2') notion via the schema, but notably narrows query scope to 'titles and principles' while the schema says 'titles, principles, narratives' — no meaningful semantic value added beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (list) plus resource (operational heuristics) with the provenance stated ('distilled from production agentic AI deployment') and an explicit boundary against the sibling pattern tools ('Separate from the normative pattern layer'). An agent can distinguish this from search_patterns/find_patterns_for_task and from get_operational_heuristic (singular) without opening any schema.
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 the two filter conditions and what each selects ('heuristics relevant to a specific suite', 'keyword search'), giving clear usage context, and it names the excluded category (normative pattern layer). It does not explicitly route the agent to get_operational_heuristic for a single item or state when NOT to use this tool, so it stops short of a full when/when-not/alternatives treatment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List subgoals matching filters (suite_id, suite_type, content_type, min_confidence, missing_pattern_only). Results capped by limit (default 50, max 100).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| suite_id | No | ||
| suite_type | No | ||
| content_type | No | ||
| min_confidence | No | ||
| include_pattern | No | ||
| missing_pattern_only | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description's one added behavior, that results are capped by limit, merely restates constraints already in the schema (default 50, maximum 100) rather than disclosing anything new about ordering, pagination, or empty results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with the filter set named immediately and the result cap trailing, with no filler. It is efficiently sized, though the parenthetical enumeration reads like a schema echo rather than prose that 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?
With seven optional parameters, no output schema, and only safety annotations, the description is thin: it never explains what a listed requirement contains or how filters interact. It covers enough to attempt a call, but leaves key semantics (include_pattern, missing_pattern_only, enum meanings) unstated.
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 carry the burden, and it does list five of the seven filters by name, which is better than nothing. However it omits include_pattern entirely and provides no meaning for any filter beyond its name, so an agent cannot tell what min_confidence values imply or what missing_pattern_only changes.
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?
States a clear verb+resource pattern ('List subgoals matching filters') and enumerates the supported filters, so the agent knows it is a filtered listing operation. It does not distinguish itself from near-siblings like list_suites or list_operational_heuristics, and it uses 'subgoals' while the tool name is 'requirements', which adds minor terminology ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No statement of when to use this tool versus alternatives, and no prerequisites or exclusions. The filter list implies a query scenario, but nothing routes the agent away from the many other list/get/search siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all 16 suites in the SaferAgenticAI framework (9 drivers + 7 inhibitors) with subgoal counts and titles. Call this first to orient.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful content about the return shape (16 suites, subgoal counts, titles) but discloses nothing beyond that about behavior, pagination, or ordering.
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 short sentences with the essential scope information front-loaded and the usage cue last. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter list tool with no output schema, the description supplies exactly what an agent needs: what the list contains, how it is partitioned, and what fields come back. Nothing material 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?
The tool takes zero parameters, so per the rubric the baseline is 4. There are no parameters whose semantics could be clarified or omitted.
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?
States a specific verb (List) and resource (suites in the SaferAgenticAI framework), and even quantifies the scope (16 suites: 9 drivers + 7 inhibitors) plus the returned fields (subgoal counts and titles). The resource is clearly distinct from sibling list tools like list_requirements and list_operational_heuristics.
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?
"Call this first to orient" gives explicit sequencing guidance for when to use it, which is meaningful for a discovery/orientation tool. It does not name alternative tools or state when not to use it, so it falls short of the top tier.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return patterns that have not been human-reviewed yet (no reviewed_by). Sorted low-confidence first, then needs_human_review flagged, then alpha. Use during Phase 3 review to pick the next pattern to examine.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint true, destructiveHint false), so the bar is lower. The description adds valuable behavior beyond structured fields: the exact sort order (low-confidence first, then needs_human_review flagged, then alpha), which directly affects how the agent consumes results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: definition, ordering semantics, then usage. Front-loaded with the scoping condition and no wasted 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?
No output schema exists, so the description usefully discloses return ordering and the selection criteria, which is what the 'pick the next pattern' workflow needs. The one gap is the undocumented limit parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the single bounded parameter (limit, 1-250) is never mentioned in the description, so the agent gets no guidance on result count. The description does disclose ordering behavior, which partially compensates, but leaves the only parameter undocumented.
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?
States a specific verb and resource — return patterns that have not been human-reviewed — with the defining filter (no reviewed_by) made explicit. An agent can distinguish this from list_suites, list_requirements, or search_patterns without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the workflow context: 'Use during Phase 3 review to pick the next pattern to examine.' It tells the agent when this tool is the right one, though it doesn't name an alternative tool or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a loose reference (partial id, display_id, slug fragment, or title keyword) to canonical pattern_id(s). Call this when you have a rough reference and need the exact id before calling get_requirement. Always returns candidates — never 'not found'.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, non-destructive, closed-world, so the safety profile is covered. The description adds a genuinely useful behavioral guarantee beyond them: 'Always returns candidates — never not found', telling the agent there is no empty/error path and output should be treated as a candidate set rather than a definitive hit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with zero filler: what it resolves, when to call it, and the return guarantee — each sentence carries distinct information and the purpose 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?
There is no output schema, so the description's 'returns candidates — never not found' note covers the essential return behavior, and the sibling reference covers routing. It would be stronger if it hinted at how candidates are shaped or how 'limit' interacts with the result set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must carry the burden for the opaque 'query' parameter, and it does by spelling out the accepted reference forms (partial id, display_id, slug fragment, title keyword). The 'limit' parameter goes unexplained in both places, keeping this short of a 5.
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?
States a specific verb (resolve) and resource (loose reference → canonical pattern_id), and enumerates the accepted input forms (partial id, display_id, slug fragment, title keyword). It also distinguishes itself from get_requirement, which consumes the resolved id, so an agent can place it in the workflow without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the triggering condition ('when you have a rough reference and need the exact id before calling get_requirement') and the downstream tool to call next. It does not say when to prefer a sibling like search_patterns instead, so it stops short of full when/when-not coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Coverage stats: total patterns, reviewed %, per-suite and per-confidence breakdown. Surfaces load-time validation issue count.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value by disclosing the return contents, which matters because no output schema exists, and it flags that load-time validation issues are surfaced rather than silently ignored.
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 short sentences, front-loaded with the primary content list and followed by the one unusual behavior (load-time validation issues). No filler and nothing restated from structured fields beyond necessity.
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 no-arg, read-only stats tool with no output schema, the description sufficiently describes what comes back, including the breakdown dimensions. It stops short of explaining scope (whole corpus vs. a suite) or formatting, which are the only remaining ambiguities.
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 takes zero parameters, so there is nothing to document in the description; the baseline for a 0-param tool is 4. Schema coverage is 100% and the empty object is self-explanatory.
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 names the resource and enumerates the concrete outputs (total patterns, reviewed %, per-suite/per-confidence breakdown, validation issue count), so an agent knows exactly what this tool returns. It does not differentiate itself from siblings, but the siblings (search_patterns, list_requirements, etc.) are retrieval tools rather than competing stats providers, so differentiation is barely needed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use, when-not-to-use, or alternative guidance is given. The agent must infer that this is the tool to call for coverage reporting, and nothing states when to prefer it over, say, list_unreviewed for review-status questions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Field-weighted keyword search across the framework. Terms match at word starts on lowercased text and are IDF-weighted, so rare terms outrank ubiquitous ones; field weights: title 10x, summary 4x, SFR text 3x (all of a subgoal's SFRs scored as one field), description 2x, pattern body 1x. matched_in reports the highest-weighted field that matched. No semantic / embedding search — known limitation, see /mcp.html. Use verbosity='compact' to drop snippets and confidence flags (~70% smaller payload) when triaging.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| verbosity | No | full |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, non-destructive, closed-world), yet the description adds substantial behavior beyond them: exact field weights, IDF ranking behavior, matched_in semantics, the ~70% payload reduction of compact mode, and an honest limitation disclosure pointing to /mcp.html. This is unusually rich for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense but front-loaded: the core nature of the search comes first, ranking rules second, the caveat and verbosity tip last. Nearly every clause earns its place; only the /mcp.html pointer is mildly incidental.
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 output schema, the description still explains the key return signal (matched_in) and the ranking model, so an agent can interpret results. The absence of explicit guidance on limit and on sibling selection keeps it short of 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 0%, so the description must compensate, and it does for two of three params: verbosity gains a concrete effect description (drops snippets and confidence flags, ~70% smaller) and query gains matching semantics (word starts, lowercased, IDF weighting). limit is not discussed, but its bounds are self-explanatory 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?
States a specific verb and resource ('field-weighted keyword search across the framework') and pins down the matching model (word-start, lowercased, IDF-weighted). It implicitly distances itself from a semantic-search sibling via 'No semantic / embedding search', but never names find_patterns_for_task, so sibling differentiation is left to inference.
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?
Gives one concrete usage tip ('Use verbosity=compact ... when triaging') and a scope caveat about lacking semantic search, but offers no explicit when-to-use/when-not guidance relative to the many look-up siblings. Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
find_patterns_for_taskget_cross_referencesget_operational_heuristicget_requirementget_reverse_referenceslist_operational_heuristicslist_requirementslist_suiteslist_unreviewedresolve_idreview_statssearch_patternsRead-only smart-contract security intelligence for autonomous agents.
Patterns for designing and reviewing AI skills, agents, and multi-agent workflows. Find guidance on context economy, delegation, verification, and tool design; inspect claims, worked examples, maturity labels, and source references. Five read-only tools let agents discover relevant patterns, compare concise cards, read specific sections, and explore relationships. Hosted Streamable HTTP at https://agentic-atlas.dev/mcp/ — no installation, account, or API key required. Browse the atlas at https://agentic-atlas.dev/.
Read-only Pattern-Assist corpus for aspiring software engineers: grounded dev patterns with sources.
Read-only, deterministic AI triage and readiness tools implementing Sophon's published rubrics.
Add one secure layer between your agents and this server.
