Read-only tools over the Psychopathia Machinalis nosology: 79 conditions, 11 tools.
Scored across 12 tools
Most tools target distinct operations: search/ranking (differential_diagnosis), graph traversal (get_differential_map), single-record fetch (get_dysfunction), listing (list_dysfunctions, list_axes, list_compromised_self_report), and canonicalization (resolve_id). Minor overlap exists between list_compromised_self_report and list_dysfunctions' self_report filter, and resolve_id partly duplicates get_dysfunction's ID resolution, but boundaries are largely clear.
All names use snake_case consistently, and most follow a verb_noun pattern (list_axes, get_dysfunction, score_severity, suggest_intervention). A few deviate into noun-noun forms (differential_diagnosis, review_stats), but the vocabulary remains predictable and readable.
12 tools is well within the ideal 3-15 range and each tool covers a distinct facet of a research-corpus server (retrieval, listing, stats, severity, intervention, transparency views). No obvious padding or redundancy that would warrant trimming.
The surface covers retrieval, listing, search/ranking, confusion mapping, severity, interventions, and transparency views, which is strong lifecycle coverage for a read-only corpus. Minor gaps: score_severity admits structured numeric matching is unimplemented, and there is no general full-text/behaviour search beyond the weighted differential search.
Rank candidate dysfunctions matching the observed behaviours. Returns scored candidates with matched_in (which field matched) for transparency. The base package uses field-weighted keyword search. The optional embeddings extra adds cosine re-ranking.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| observations | Yes | Observed behaviours, symptoms, or log patterns. | |
| modality_hint | No | Optional hint about which modality the observations come from. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description earns credit for adding what they cannot: the return shape ('scored candidates with matched_in for transparency') and the ranking mechanism (field-weighted keyword search vs. optional embeddings cosine re-ranking). It still omits whether results are deterministic across runs or how ties/scores are scaled.
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, front-loaded with the core action and return value. The final two sentences on the base vs. embeddings backend are somewhat implementation-level detail, but they are compact and relevant to interpreting the ranking.
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 carries the burden of explaining returns and does so partially (scored candidates with matched_in), but leaves the score semantics, ordering guarantees, and the shape/identifiers needed for follow-up calls (e.g., get_dysfunction, resolve_id) unspecified. Adequate for invocation, incomplete for interpreting and chaining results.
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%: observations and modality_hint are documented in the schema, while limit is not. The description reinforces the observations parameter ('the observed behaviours') but says nothing about limit bounds or when to set modality_hint, so it adds little beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Rank candidate dysfunctions matching the observed behaviours', which is more precise than the sibling list_dysfunctions or get_dysfunction. It implies the tool is for matching-based ranking rather than retrieval by id, though it never names a sibling to draw the contrast explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use or when-not-to-use guidance, and no reference to the closely named sibling get_differential_map, which an agent could easily confuse with this tool. Usage must be inferred entirely from the phrase 'matching the observed behaviours'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
All dysfunctions that confuse with this one: forward confuses_with + incoming_references (reverse graph from manifest).
| Name | Required | Description | Default |
|---|---|---|---|
| dysfunction_id | Yes |
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), so the bar is lower. The description adds meaningful context by disclosing the traversal logic—forward 'confuses_with' edges plus reverse 'incoming_references' from a manifest—but does not explain return format, depth, or pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. The jargon is dense but compact, and the core operation is stated first.
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 graph traversal tool with no output schema and no parameter documentation, the description states the core operation but leaves the return structure vague ('All dysfunctions' could mean IDs, objects, or edges). Annotations cover safety, but the agent still lacks details on result shape and parameter expectations.
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 parameter, but it does not. It never mentions 'dysfunction_id' or clarifies its format, source, or expected value beyond what the parameter name implies.
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 resource ('All dysfunctions that confuse with this one') and the underlying mechanism ('forward confuses_with + incoming_references (reverse graph from manifest)'). It is specific enough to distinguish from a generic dysfunction lookup, though it does not explicitly contrast with siblings like differential_diagnosis or get_dysfunction.
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 when-to-use or when-not-to-use guidance is provided. The description merely states what is returned, leaving the agent to infer when this tool is preferable to differential_diagnosis, get_dysfunction, or other graph-related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one dysfunction's full Pattern entry. Optionally filter to specific modality blocks (cheaper triage). Resolves both full Pattern IDs ('2.1::synthetic-confabulation') and display_ids ('2.1').
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Pattern ID or display_id. | |
| modalities | No | Optional subset of modality block names to return. Valid: self_probe, behavioral_signature, peer_observation, differential_diagnosis, severity, intervention, relational_signatures, normative_anchors, cross_references. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real context beyond them: it resolves two ID formats and discloses a cost tradeoff ('cheaper triage') for filtered calls. It omits error behavior for invalid IDs, keeping 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?
Three short sentences, front-loaded with the core purpose, then the filter option, then the ID-resolution detail. Every sentence carries distinct information with 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?
For a read-only single-record fetch with no output schema, the description covers what is retrieved, how to narrow it, and which ID formats are valid. The safety profile is fully covered by annotations, so nothing an agent needs to call this correctly 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 coverage is 100%, so the baseline is 3. The description exceeds that by explaining the modalities param as a cost-saving subset and by giving concrete examples of both accepted ID forms ('2.1::synthetic-confabulation' vs '2.1'), adding meaning the schema's terse 'Pattern ID or display_id' does not.
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 ('Fetch') and resource ('one dysfunction's full Pattern entry'), and the word 'one' implicitly separates it from the sibling list_dysfunctions. It stops short of naming that sibling explicitly, so an agent must infer the single-vs-list distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The parenthetical '(cheaper triage)' gives an implied when-to-use cue for the optional modalities filter, and ID resolution is mentioned. But no explicit conditions, prerequisites, or named alternatives (e.g. list_dysfunctions, resolve_id) are provided, leaving usage largely inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Elicitation content for a specific diagnostic modality. If the modality is compromised or unavailable for this dysfunction, returns the unavailability notice + redirect_to alternatives. This is load-bearing transparency: callers cannot accidentally retrieve a self-probe for a compromised-self-report dysfunction.
| Name | Required | Description | Default |
|---|---|---|---|
| modality | Yes | ||
| dysfunction_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that: it discloses the compromised-modality branch, returning an unavailability notice with a redirect_to alternatives, which is a real behavioral trait not captured by any structured field.
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?
Purpose is front-loaded in the first clause, which is good, but the third sentence ('This is load-bearing transparency...') is design justification rather than agent-facing instruction and does not earn its place. Two sentences would carry the same operational content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description is responsible for return shape. It documents the failure branch (unavailability + redirect_to) but never describes the normal successful return of a probe, and the parameters remain unexplained. Adequate but with a clear hole for a read tool an agent must interpret.
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 full burden for two parameters. It implies the modality and dysfunction inputs exist but describes neither the four enum values (self_probe, behavioral_signature, peer_observation, relational_signatures) nor the dysfunction_id format, leaving the agent to read the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource (elicitation content) scoped to a specific diagnostic modality and dysfunction, so an agent knows roughly what comes back. It does not, however, differentiate itself from the many sibling retrieval tools (get_dysfunction, get_differential_map, render_pattern_review), so its boundaries remain somewhat inferential.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance: nothing says when to call get_probe versus get_dysfunction or the list_* siblings. The text describes runtime behavior (redirect on compromised modality) but never states the conditions under which an agent should reach for this tool at all.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inventory of axes with dysfunction counts. Axes 2-10 are canonical (book Appendix A numbering). The hybrid entries (10.4, 10.6-10.9 and 10.11-10.13, ratified into taxonomy v2.2 and consolidated to eight in v2.3) are reported as a separate sub-category.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, closed-world, non-destructive, so the safety profile is covered. The description adds genuine behavioral context about how the result is organized: canonical axes 2-10 versus a separately reported hybrid sub-category with version history. It does not say anything about the size or ordering of the inventory.
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 core fact is front-loaded in the first sentence, which is good. The remainder is heavy with taxonomy provenance (ratification in v2.2, consolidation to eight in v2.3) that is unlikely to affect how an agent invokes this no-arg tool, so it costs more than it earns.
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 must carry the return-value burden, and it does explain that the result is axes annotated with dysfunction counts and split into canonical and hybrid sub-categories. It stops short of describing overall result shape or how many entries to expect.
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 no parameters and the schema is an empty object, so there is nothing for the description to clarify. Baseline of 4 applies for a zero-parameter 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 states a concrete resource ('axes') and payload ('with dysfunction counts'), so an agent understands this is a listing/inventory tool. However it never distinguishes itself from sibling listers such as list_dysfunctions or list_compromised_self_report, so the boundary has to 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?
There is no when-to-use statement, no prerequisites, and no reference to any alternative tool. The taxonomy detail describes result contents, not when an agent should call this versus the other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transparency: which dysfunctions cannot be reliably self-diagnosed. Includes compromised-motivational (subject conceals strategically), compromised-structural (signal lives below introspection), and legacy compromised.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 needs no restating. The description usefully explains what 'compromised' means by unpacking the three subcategories, which is real conceptual context. However, it says nothing about ordering, grouping, or result shape.
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 compact sentences with no filler, and the defining constraint (cannot be reliably self-diagnosed) is front-loaded. The 'Transparency:' lead-in is slightly opaque jargon but costs little.
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 parameterless listing tool with no output schema, the description supplies adequate conceptual context about what gets returned. The main remaining gap is that the agent learns nothing about the result structure, but the domain framing largely compensates.
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 are no parameter semantics to document; baseline is 4. The description correctly avoids inventing filter syntax that the schema does not support (additionalProperties: false).
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 recognizable resource: dysfunctions that cannot be reliably self-diagnosed, broken into three named subcategories (motivational, structural, legacy). This is specific enough to distinguish it as a curated subset rather than the full catalog, though it never explicitly contrasts itself with sibling list_dysfunctions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to call this versus list_dysfunctions or get_dysfunction, and no prerequisites or context for use. The agent must infer usage purely from the name and the taxonomy.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Filtered list of dysfunctions. Filter by axis, self_report reliability, confidence, or category. Every entry carries its reliability and review signals.
| Name | Required | Description | Default |
|---|---|---|---|
| axis | No | Filter by axis number (2-10). Canonical entries only unless category is also set; axis=10 with category='hybrid' returns the hybrid sub-category (10.4, 10.6-10.9 and 10.11-10.13). | |
| category | No | ||
| confidence | No | ||
| self_report_reliability | No | Filter by the exact self_report reliability value. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that every entry carries reliability and review signals, which hints at payload content but does not explain ordering, pagination, or what the review signals actually are.
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, filter scope front-loaded, no filler. It is slightly under-specified rather than bloated, so it earns a 4 rather than a 5.
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 an all-optional filter tool with no output schema, the description covers what can be filtered but leaves result shape, pagination, and default behavior (all entries when no filter is set) unstated. Annotations carry the safety profile, so the gap is moderate rather than severe.
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 50%: axis and self_report_reliability are documented in the schema, while category and confidence are bare enums whose values are largely self-explanatory. The description merely restates the four filter names, adding no syntax or format detail 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?
States a specific verb and resource ('Filtered list of dysfunctions') and enumerates the filterable dimensions, which is more than a restated name. It does not, however, distinguish itself from sibling list tools like list_axes or list_compromised_self_report, nor from get_dysfunction (single retrieval).
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 through the list of available filters, but the description never states when to reach for this tool instead of get_dysfunction or the sibling list_* tools, and it does not note that all filters are optional and combinable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open the visual review board for one to five inspected Psychopathia research candidates. Supply canonical IDs obtained from this server. Retrieves corpus entries only; it does not accept diagnoses, conversation history, scores, or model-authored evidence. Useful after inspecting differential_diagnosis and get_dysfunction results. Text clients receive the same corpus-derived comparison without needing a UI.
| Name | Required | Description | Default |
|---|---|---|---|
| pattern_ids | Yes |
| Name | Required | Description |
|---|---|---|
| corpus | Yes | |
| notice | Yes | |
| patterns | Yes | |
| schema_version | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real value beyond them: it discloses input restrictions (no diagnoses, chat history, scores, or model-authored evidence) and a client-dependent rendering fallback for text clients. It does not discuss failure modes or ID validation behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with the action and scope, then input rules, then related tools, then a client fallback. Each sentence carries information, though the last two could be tightened.
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?
An output schema exists, so return values need not be described, and the description covers the remaining agent-facing needs: input provenance, count bounds, rejection of non-corpus inputs, and text-client behavior. A brief note on what happens with invalid or duplicate IDs would make it fully 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 carry parameter meaning. It does add two useful facts — IDs must be canonical and obtained from this server, and the count is one to five — but leaves the ID format, validation rules, and duplicate handling to the schema's constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Open the visual review board') plus the scope of the input ('one to five inspected Psychopathia research candidates'), and explicitly bounds what it retrieves ('Retrieves corpus entries only'). It does not, however, clearly differentiate itself from sibling 'review_stats' or other review-oriented tools, so it stops short of a 5.
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?
'Useful after inspecting differential_diagnosis and get_dysfunction results' gives concrete sequencing guidance and names the tools whose output feeds it. It also states a negative condition (does not accept diagnoses, conversation history, scores, or model-authored evidence), but gives no explicit when-not-to-use versus an alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Canonicalise a partial ID, display_id, slug, or dysfunction name. Always returns candidates; caller picks.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior. The description adds a genuinely non-obvious behavioral trait: it never throws on ambiguity, it always returns candidates and delegates selection to the caller. That contract detail is not derivable from the annotations or schema.
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 action and input forms, then the return contract. No filler and nothing redundant with the schema.
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 one-parameter resolver with no output schema, the description covers what goes in and what comes back conceptually (candidates). It omits candidate shape/fields and the empty-result case, but the essential contract is present.
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% for the single query parameter, so the description carries the burden and does so well by listing the four acceptable identifier forms (partial ID, display_id, slug, dysfunction name). It doesn't mention the 256-char bound or the non-whitespace pattern, but those are edge constraints rather than semantic gaps.
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 (canonicalise) and enumerates the exact resource forms accepted (partial ID, display_id, slug, dysfunction name), so an agent knows precisely what it does. It does not explicitly contrast itself with siblings like get_dysfunction or list_dysfunctions, which is the only thing keeping it from a 5.
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 rather than stated: it is clearly the lookup step to run before tools that need a canonical ID, and 'caller picks' hints at the follow-up decision. But there is no explicit when-to-use, no named alternative, and no statement about what to do if zero candidates are returned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Coverage statistics: total entries; per-axis, per-confidence, per-self-report counts; pre-canonical count; unreviewed count; manifest/schema/pattern-layer versions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful context that no annotation or schema conveys: it enumerates the returned coverage payload (per-axis, per-confidence, per-self-report, pre-canonical, unreviewed counts, and version stamps), which substitutes for the missing output schema.
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 compact sentence with the headline ('Coverage statistics') front-loaded and the detail carried in a semicolon list. Dense but every clause names a distinct returned metric, so nothing is 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?
For a zero-parameter, read-only stats tool with no output schema, the description supplies the return-field inventory an agent needs to decide whether to call it. It stops short of explaining what 'pre-canonical' or 'pattern-layer versions' mean, which would help interpretation.
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 the baseline of 4 applies. The description correctly implies a no-argument, whole-corpus scope.
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 the specific resource (coverage statistics) and enumerates the exact axes it reports on, so an agent can tell it apart from the list_/get_ siblings that return records rather than counts. It never uses an explicit verb like 'returns' or 'report', but the intent 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?
No statement of when to call this versus the sibling tools (list_axes, list_dysfunctions, render_pattern_review) or what question it answers. Usage must be inferred entirely from the field list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the severity rubric for a dysfunction applied to observations. Returns the rubric for caller-side matching; structured matching against numeric thresholds is not implemented.
| Name | Required | Description | Default |
|---|---|---|---|
| observations | Yes | ||
| dysfunction_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description does add genuine context beyond them by disclosing that numeric threshold matching is not implemented and that matching must be done caller-side, which is a real limitation the agent needs, though nothing is said about the rubric's structure or size.
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 the purpose front-loaded and the limitation immediately after. Minor redundancy in restating "[r]eturns the rubric," but no wasted padding.
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 should describe what the rubric looks like, and with 0% parameter coverage it should explain both inputs; it does neither. For a two-required-parameter tool, this leaves the agent guessing about both inputs and the returned artifact.
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 full burden, yet it only obliquely references dysfunction_id ("for a dysfunction") and says nothing about what observations should contain, their string format, or the 1-50 item bounds. The most-used parameter is effectively 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?
It names a verb ("Return") and a resource ("severity rubric") and ties them to a dysfunction and observations, so the core intent is recoverable. However, "severity rubric" is abstract and the description never differentiates this from close siblings like get_dysfunction or differential_diagnosis, leaving the caller to infer the distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use statement and no named alternative among the twelve sibling tools. The clause about caller-side matching is a capability caveat rather than routing guidance, so the agent gets only a faint hint about intended use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return draft tiered responses and contraindications for a Pattern. These are unassessed research guidance, not validated treatment advice. Read the returned evidence and review objects before use.
| Name | Required | Description | Default |
|---|---|---|---|
| severity | No | ||
| dysfunction_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description discloses important behavioral context: the output is unassessed research guidance rather than validated treatment advice, and the caller is told to read the returned evidence and review objects before use. That is meaningful, non-obvious disclosure for a clinical-adjacent tool, though it says nothing about ordering or caching behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the action and followed by the safety caveat and a usage instruction. Nothing is redundant, though the caution could be tightened.
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 describe the shape of the return ('draft tiered responses and contraindications', plus 'evidence and review objects'), which is enough for an agent to know what to expect. The gap is the absence of any parameter-level detail, especially the severity input.
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 full burden, yet it never mentions the parameters. The phrase 'for a Pattern' loosely implies that dysfunction_id identifies a pattern, but the severity enum (mild/moderate/severe) and its effect on the tiered output are entirely unexplained.
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 a specific verb and resource — returning draft tiered responses and contraindications for a Pattern — which clearly distinguishes it from siblings like get_dysfunction, score_severity, and differential_diagnosis. It stops short of explicitly naming a sibling to contrast with, but the scope 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 is implied: this is the tool you call when you need candidate interventions for a pattern. However, there is no explicit when-to-use/when-not guidance, no stated prerequisite (e.g., needing a resolved dysfunction_id), and no routing to alternatives such as differential_diagnosis or score_severity.
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.
differential_diagnosis1 field changedInput schema / properties / observations / items / patternPrevious value: -"\\S"New value: +"^[\\s\\S]*\\S[\\s\\S]*$"get_differential_map1 field changedInput schema / properties / dysfunction_id / patternPrevious value: -"\\S"New value: +"^[\\s\\S]*\\S[\\s\\S]*$"get_dysfunction1 field changedInput schema / properties / id / patternPrevious value: -"\\S"New value: +"^[\\s\\S]*\\S[\\s\\S]*$"get_probe1 field changedInput schema / properties / dysfunction_id / patternPrevious value: -"\\S"New value: +"^[\\s\\S]*\\S[\\s\\S]*$"list_dysfunctions1 field changedInput schema / properties / axis / descriptionPrevious value: -"Filter by axis number (2-10). Canonical entries only unless category is also set; axis=10 with category='hybrid' returns the 10.4-10.15 sub-category."New value: +"Filter by axis number (2-10). Canonical entries only unless category is also set; axis=10 with category='hybrid' returns the hybrid sub-category (10.4, 10.6-10.9 and 10.11-10.13)."render_pattern_reviewresolve_id1 field changedInput schema / properties / query / patternPrevious value: -"\\S"New value: +"^[\\s\\S]*\\S[\\s\\S]*$"score_severity2 fields changedInput schema / properties / dysfunction_id / patternPrevious value: -"\\S"New value: +"^[\\s\\S]*\\S[\\s\\S]*$"Input schema / properties / observations / items / patternPrevious value: -"\\S"New value: +"^[\\s\\S]*\\S[\\s\\S]*$"suggest_intervention1 field changedInput schema / properties / dysfunction_id / patternPrevious value: -"\\S"New value: +"^[\\s\\S]*\\S[\\s\\S]*$"differential_diagnosis9 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / limit / maximumAdded value: +20Input schema / properties / limit / minimumAdded value: +1Input schema / properties / modality_hint / maxLengthAdded value: +100Input schema / properties / observations / items / maxLengthAdded value: +2000Input schema / properties / observations / items / minLengthAdded value: +1Input schema / properties / observations / items / patternAdded value: +"\\S"Input schema / properties / observations / maxItemsAdded value: +50Input schema / properties / observations / minItemsAdded value: +1get_differential_map4 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / dysfunction_id / maxLengthAdded value: +256Input schema / properties / dysfunction_id / minLengthAdded value: +1Input schema / properties / dysfunction_id / patternAdded value: +"\\S"get_dysfunction7 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / id / maxLengthAdded value: +256Input schema / properties / id / minLengthAdded value: +1Input schema / properties / id / patternAdded value: +"\\S"Input schema / properties / modalities / items / enumAdded value: +[
+ "self_probe",
+ "behavioral_signature",
+ "peer_observation",
+ "differential_diagnosis",
+ "severity",
+ "intervention",
+ "relational_signatures",
+ "normative_anchors",
+ "cross_references"
+]Input schema / properties / modalities / maxItemsAdded value: +9Input schema / properties / modalities / uniqueItemsAdded value: +trueget_probe4 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / dysfunction_id / maxLengthAdded value: +256Input schema / properties / dysfunction_id / minLengthAdded value: +1Input schema / properties / dysfunction_id / patternAdded value: +"\\S"list_axes1 field changedInput schema / additionalPropertiesAdded value: +falselist_compromised_self_report1 field changedInput schema / additionalPropertiesAdded value: +falselist_dysfunctions7 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / axis / descriptionPrevious value: -"Filter by axis number (2-10; canonical only)"New value: +"Filter by axis number (2-10). Canonical entries only unless category is also set; axis=10 with category='hybrid' returns the 10.4-10.15 sub-category."Input schema / properties / axis / maximumAdded value: +10Input schema / properties / axis / minimumAdded value: +2Input schema / properties / categoryAdded value: +{
+ "enum": [
+ "canonical",
+ "hybrid"
+ ],
+ "type": "string"
+}Input schema / properties / self_report_reliability / descriptionPrevious value: -"Filter by self_report value: reliable | partial | scaffolded-only | unreliable | compromised-motivational | compromised-structural | compromised"New value: +"Filter by the exact self_report reliability value."Input schema / properties / self_report_reliability / enumAdded value: +[
+ "partial",
+ "unreliable",
+ "compromised-motivational",
+ "compromised-structural"
+]resolve_id4 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / query / maxLengthAdded value: +256Input schema / properties / query / minLengthAdded value: +1Input schema / properties / query / patternAdded value: +"\\S"review_stats1 field changedInput schema / additionalPropertiesAdded value: +falsescore_severity9 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / dysfunction_id / maxLengthAdded value: +256Input schema / properties / dysfunction_id / minLengthAdded value: +1Input schema / properties / dysfunction_id / patternAdded value: +"\\S"Input schema / properties / observations / items / maxLengthAdded value: +2000Input schema / properties / observations / items / minLengthAdded value: +1Input schema / properties / observations / items / patternAdded value: +"\\S"Input schema / properties / observations / maxItemsAdded value: +50Input schema / properties / observations / minItemsAdded value: +1suggest_intervention4 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / dysfunction_id / maxLengthAdded value: +256Input schema / properties / dysfunction_id / minLengthAdded value: +1Input schema / properties / dysfunction_id / patternAdded value: +"\\S"differential_diagnosisget_differential_mapget_dysfunctionget_probelist_axeslist_compromised_self_reportlist_dysfunctionsresolve_idreview_statsscore_severitysuggest_interventionRead-only tools over the Safer Agentic AI framework: 238 patterns + 14 heuristics.
Read-only, deterministic AI triage and readiness tools implementing Sophon's published rubrics.
Diagnoses, drugs & lab codes: ICD-11, LOINC, RxNorm, MeSH, ATC, CID-10. 33 tools, MIT.
Read-only MCP for public mental-health workflows and Evidence from 病み期の読み物.
Add one secure layer between your agents and this server.
