Read-only tools over the Psychopathia Machinalis nosology: 79 conditions, 11 tools.
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?
No annotations are provided, so the description carries the burden. It discloses the return format (scored candidates with matched_in) and the two scoring modes (keyword vs embeddings), adding transparency beyond the schema. However, it does not mention any side effects or safety implications, though a diagnosis tool is likely read-only.
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 primary purpose, followed by output format and algorithmic detail. No extraneous information. Highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the return value (scored candidates with matched_in) and the scoring mechanism. It covers the essential behavior for an agent to call the tool correctly. It doesn't discuss edge cases or parameter behaviors, but those are sufficiently covered by the schema. The description is complete enough for a moderate-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (observations and modality_hint have descriptions, limit does not). The description adds no additional detail about parameter syntax or constraints beyond what the schema provides. It does mention 'matched_in' which is an output field, not a parameter. The moderate coverage means the description doesn't need to compensate heavily, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Rank') and resource ('candidate dysfunctions') and clarifies the output (scored candidates with matched_in). It distinguishes from siblings by focusing on ranking based on observed behaviours, which is unique among the listed tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the underlying search algorithm (field-weighted keyword vs embeddings) but does not explicitly state when to use this tool over alternatives like get_differential_map or get_dysfunction. It provides context but lacks explicit when/when-not guidance, leaving the agent to infer the appropriate use case.
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?
With no annotations, the description carries the full burden of behavioral disclosure. It reveals some internal mechanics (reverse graph from manifest) but does not mention side effects, return format, error behavior, or whether the operation is read-only. This is minimal disclosure for a graph-query 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?
The description is short and front-loaded, but the single sentence is cryptic and uses jargon ('confuses_with', 'incoming_references') without explanation. It is concise in length but not in clarity, so it only partially earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a graph-based tool with no output schema, the description is incomplete. It does not explain the structure of the returned data, pagination, ordering, or edge cases. With many siblings, it also fails to differentiate itself adequately, leaving the agent without enough information to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It only implicitly refers to 'this one' as the dysfunction_id, without explaining its role, format, or how it is used in the graph traversal. The description adds little meaning beyond the schema's basic type 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 the tool returns dysfunctions that confuse with the given one, and mentions combining forward confuses_with and incoming_references. However, the phrasing is cryptic ('All dysfunctions that confuse with this one') and doesn't explicitly say it returns a list or map. It is not a tautology but lacks clarity for an agent unfamiliar with the domain.
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 mention of when to use this tool versus alternatives like differential_diagnosis or get_dysfunction. No exclusions, prerequisites, or context for selection are provided, leaving the agent without guidance on appropriate invocation.
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?
With no annotations, the description carries the full burden. It discloses the ID resolution behavior (accepts both full Pattern IDs and display_ids) and that it returns the full entry or a filtered subset. It does not mention read-only nature, error handling, or side effects, but for a fetch operation these are less critical. The ID resolution detail is valuable behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both dense with information. The primary purpose is front-loaded, and the optional filtering and ID resolution details follow logically. There is zero fluff, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch tool with two parameters and no output schema, the description is fairly complete. It explains what is returned (full Pattern entry or filtered blocks) and clarifies ID formats. It doesn't detail the structure of the response, but that is likely implied by the domain. Minor gaps like error behavior exist but are not critical for a get operation.
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 both parameters are documented. The description adds meaning beyond the schema by explaining that the id parameter can be either a full Pattern ID or display_id, and by giving the purpose of the modalities parameter as 'cheaper triage'. This provides context that the schema alone 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?
The description clearly states the action ('Fetch') and the resource ('one dysfunction's full Pattern entry'), and adds the optional filtering capability. It distinguishes itself from list_dysfunctions by focusing on a single entry, though it doesn't explicitly name alternatives. This is specific and clear, but not maximal because sibling differentiation is implicit rather than explicit.
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 mentions the optional modality filter with the rationale 'cheaper triage', which gives some guidance on when to use that feature. However, it doesn't provide any explicit when-to-use or when-not-to-use guidance relative to sibling tools like list_dysfunctions or get_probe. The usage context is partially implied but not fully specified.
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?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It does so by explicitly stating that if the modality is compromised, the tool returns an unavailability notice and redirects to alternatives. It also emphasizes a safety guarantee ('callers cannot accidentally retrieve a self-probe for a compromised-self-report dysfunction'), which adds valuable transparency. This goes beyond a simple 'retrieves content' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences and reasonably concise. It leads with the primary purpose, then covers an important edge case, and ends with a transparency note. Every sentence adds information, though the final sentence ('This is load-bearing transparency...') is somewhat abstract and could be trimmed without losing core meaning. Overall, it is well-structured and not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two parameters, no output schema, and no annotations, the description is only partially complete. It covers the main purpose and an important failure mode, but it does not describe the structure of the returned 'elicitation content' or the unavailability notice format. It also omits details about success responses and how the redirect_to alternatives are represented. For an agent to fully use this tool, more information about the output would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate for parameter documentation. It mentions 'specific diagnostic modality' and 'for this dysfunction,' which hint at the two parameters (modality and dysfunction_id), but it does not explain their types, formats, or the meaning of the modality enum values. The description fails to add meaningful semantic detail beyond what the schema's parameter names alone suggest.
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 clear action: 'Elicitation content for a specific diagnostic modality.' This specifies a resource (elicitation content) and the context (diagnostic modality). It distinguishes from siblings like get_dysfunction or get_differential_map by focusing on modality-specific content. However, the term 'elicitation content' is somewhat vague and could be clearer about what is being retrieved.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context by describing behavior when a modality is compromised (returns unavailability notice + redirect_to alternatives), implying when this tool is useful. However, it does not explicitly state when to use this tool versus alternatives like get_dysfunction or get_differential_map, nor does it mention exclusions or prerequisites. The guidance is implicit rather than explicit.
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). Hybrid entries (10.4-10.15, ratified into taxonomy v2.2) 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?
With no annotations, the description carries the full burden of behavioral disclosure. It indicates the output is an inventory with counts and explains numbering, but does not explicitly state it is read-only, mention return format, ordering, or any other behavioral traits. This is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste. The main purpose is front-loaded, and the numbering detail is relevant and efficiently stated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple no-parameter list tool, the description is largely complete. It specifies the content (axes with counts) and the numbering convention. It could optionally mention return format or ordering, but nothing essential is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, so the baseline is 4. The description correctly implies no inputs are needed, and schema coverage is trivially 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is an inventory of axes with dysfunction counts, and clarifies canonical numbering and hybrid sub-category. It is specific about the resource and scope, but does not explicitly differentiate from sibling tools like list_dysfunctions, so it falls 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?
No guidance is provided on when to use this tool versus alternatives such as list_dysfunctions or get_dysfunction. The description only states what the tool returns, leaving the agent to infer usage context.
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?
With no annotations, the description carries the full burden. It discloses the scope (which dysfunctions are included) but does not describe the return value structure, whether it is read-only (implied but not stated), or any limitations. The categories are explained, but the behavioral contract is incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with 'Transparency' to set context, and lists categories with brief explanations. It is efficient with no fluff, though the opening word could be clearer about the action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no output schema and no annotations, the description is sparse. It does not state what the result looks like (e.g., IDs, names, details), nor does it relate to sibling tools. An agent would struggle to know exactly what to expect from the call, making the description incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is trivially complete. The description adds context about the content of the list, which is not required for parameters. Baseline of 4 is appropriate because no parameter documentation is needed.
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 the tool lists dysfunctions that cannot be reliably self-diagnosed, and enumerates three categories. The verb 'list' and resource 'compromised self-report' are clear from the name and description. However, it does not explicitly state the output format or differentiate itself from siblings like list_dysfunctions, which weakens precision.
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 guidance is given on when to use this tool versus alternatives such as list_dysfunctions or differential_diagnosis. The description provides no context for selection criteria or exclusions, leaving the agent to infer the intended use.
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 10.4-10.15 sub-category. | |
| 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?
No annotations are present, so the description carries the full burden. It only discloses that each entry includes reliability and review signals, but does not explain default behavior when no filters are applied, how multiple filters combine (AND/OR), sorting, pagination, or any limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences with no filler. It front-loads the core purpose and filters, and each sentence adds distinct value (function, filters, content guarantee).
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 and no annotations, the description is incomplete. It doesn't specify the return structure, the behavior with multiple filters, or the relationship to sibling tools. An agent would not know whether this returns all dysfunctions by default or how to combine filters correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50% (axis and self_report_reliability have descriptions; category and confidence do not). The description merely lists the filter names without adding semantic detail, failing to compensate for the missing schema descriptions of the enum-only parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a filtered list of dysfunctions and enumerates the filterable fields (axis, self_report reliability, confidence, category). It is distinct from siblings like list_axes (which lists axes) and get_dysfunction (which fetches a single item), though it doesn't explicitly name these alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to choose this tool over alternatives. It doesn't mention scenarios where differential_diagnosis or get_probe would be more appropriate, nor does it state any exclusions or conditions for use.
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?
With no annotations, the description carries the full burden. It discloses a key behavior: 'Always returns candidates; caller picks', which tells the agent that the tool returns multiple options and the caller must choose. However, it does not describe the structure of the candidates, error handling, or edge cases like empty results, leaving gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with two sentences that pack the core purpose, accepted inputs, and output behavior. Every word adds value, and the key behavioral note ('Always returns candidates; caller picks') is front-loaded. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers the essentials: what it does, what input it expects, and that it returns a list of candidates. It could clarify the output structure or failure modes, but given the low complexity, it is reasonably complete for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the parameter. It does state that the query can be a partial ID, display_id, slug, or dysfunction name, giving meaning to the 'query' field beyond the schema's generic string constraints. However, it lacks specifics on formatting, case sensitivity, or examples, so it only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'canonicalise' and the resource: partial IDs, display_ids, slugs, or dysfunction names. It distinguishes this tool from siblings like get_dysfunction or list_dysfunctions by focusing on resolution rather than retrieval or listing, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied: use this when you have a partial identifier that needs canonicalization. It does not state when not to use it, nor does it mention alternative tools for full IDs or other resolution scenarios. The guidance is inferable but not explicit.
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?
With no annotations, the description must carry the behavioral burden. It indicates a read-only query by stating it provides statistics, but it does not explicitly declare read-only status or absence of side effects. For a non-mutating statistics tool, this is a mild gap, not a contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, dense sentence front-loads the purpose ('Coverage statistics') and enumerates exactly what is covered. No filler words; every phrase contributes meaning.
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 statistics tool, the description lists all the metrics an agent would need. It doesn't specify the return format (e.g., JSON structure), but the enumerated list is sufficient for a caller to know what to expect. The lack of an output schema makes this adequate, not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is trivially complete. Per the baseline rule for 0-parameter tools, a score of 4 is appropriate; the description adds no parameter detail because none exists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it provides coverage statistics and enumerates specific counts (total, per-axis, per-confidence, per-self-report, pre-canonical, unreviewed) and version info. It is specific and actionable, though it doesn't explicitly differentiate from sibling tools like list_axes or get_probe, relying on the statistical nature to stand apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for viewing coverage statistics but provides no explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives. Context suggests it's the go-to for overall stats, but this is not stated, leaving the agent to infer.
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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does this well by explicitly stating the tool returns a rubric instead of performing matching, and by flagging that structured numeric-threshold matching is not implemented — a key behavioral trait an agent needs to know. It doesn't describe the return format or error behavior, but the core contract is disclosed clearly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero filler. The purpose is front-loaded in the first sentence, and the second sentence delivers the behavioral contract. Every clause earns its place with no wasted wording.
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 relatively simple two-parameter query tool with no annotations and no output schema, the description covers the essential behavior (returns rubric, no matching). However, it never describes what the returned rubric looks like or the shape of the response, which is a notable gap given there is no output schema to fill it. Adequate but not 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 both parameters. The phrase 'a dysfunction applied to observations' establishes a light relationship between dysfunction_id and observations, but adds no detail about observation format, what dysfunction_id refers to, or how they interact. With zero schema coverage, this level of compensation is insufficient.
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 ('Return') and resource ('the severity rubric for a dysfunction applied to observations'), making the tool's function clear. The second sentence adds that it returns the rubric for caller-side matching rather than performing matching itself, which meaningfully separates it from siblings like differential_diagnosis. It stops short of naming the sibling it is not, so it doesn't fully earn 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?
The phrase 'for caller-side matching; structured matching against numeric thresholds is not implemented' implies when to use this tool — when the caller wants to do its own matching. However, it never names an alternative or gives an explicit when-not-to-use statement, and none of the siblings are referenced, so the guidance is implied rather than explicit.
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?
No annotations are provided, so the description carries the full burden. It clearly discloses that the output is unassessed research guidance, not validated treatment advice, and warns to read returned evidence and review objects. This is valuable behavioral disclosure for a draft/suggestion 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 short sentences that pack a lot: what it returns, the caveat about being research guidance, and a clear warning to review before use. It is front-loaded with the purpose and uses 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?
It tells the agent what to expect in the return (draft tiered responses, contraindications, evidence, review objects) and the need for caution. However, it doesn't add needed context for parameter selection or describe how to validate or cross-check with other tool outputs, which is important given no output schema or annotations.
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?
With 0% schema description coverage, the description must explain parameters but only refers to 'a Pattern' without linking to dysfunction_id or severity. It adds no semantic meaning for either parameter, leaving the agent to guess what 'Pattern' refers to or how severity impacts output.
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?
Clearly states the tool 'Return draft tiered responses and contraindications' with a specific resource 'Pattern'. It is distinguishable from sibling tools like score_severity or differential_diagnosis, though it doesn't explicitly mention that the 'Pattern' is referenced by dysfunction_id.
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 guidance on when to use this tool versus alternatives. The only usage guidance is 'Read the returned evidence and review objects before use', which is post-call behavior, not a selection criterion.
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. Dates show when Glama detected each change.
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_interventionClaiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Read-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, SNOMED, LOINC, RxNorm, MeSH, ATC, CID-10. 33 tools, MIT.
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Add one secure layer between your agents and this server.
Each tool targets a distinct aspect of the domain: diagnosis, mapping confusions, retrieving entries, elicitation probes, listing axes/dysfunctions/compromised entries, ID resolution, statistics, severity, and interventions. No two tools overlap in purpose; descriptions clearly differentiate them.
Most tools follow verb_noun pattern (get_*, list_*, resolve_id, score_severity, suggest_intervention), but differential_diagnosis and review_stats deviate (noun-like phrases). The inconsistency is minor and doesn't obscure meaning.
11 tools is well within the ideal 3-15 range. Each tool serves a distinct purpose in the diagnostic workflow, and none feel redundant or missing for the stated domain.
The surface covers listing, retrieval, differential diagnosis, probes, severity, interventions, stats, and ID resolution. Minor gaps exist (e.g., no tool to add/update entries or directly compare two dysfunctions), but these are outside the apparent read-only research scope.
