suma-memory
Server Details
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
- Repository
- sumanaddanki/suma-mcp
- GitHub Stars
- 0
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.1/5 across 20 of 20 tools scored. Lowest: 3.1/5.
Each tool has a clearly distinct purpose, e.g., suma_clean for noise removal, suma_delete for node deletion, suma_forget for GDPR erasure, suma_ingest for new info, suma_import for bulk data. No overlapping functionality.
All tools use suma_ prefix, but there's a mix of verb and noun stems (e.g., suma_clean vs suma_entity). Minor inconsistency between singular/plural (suma_entity vs suma_entities) but pattern is mostly predictable.
20 tools is slightly above the typical 3-15 range but each tool serves a distinct function in the knowledge graph domain. Could be trimmed slightly but still reasonable for the scope.
Covers create, read, and delete operations but notably lacks any update/modify tool for existing nodes or relationships. Users must delete and re-ingest to modify, which is a significant gap for a knowledge graph system.
Available Tools
20 toolssuma_cleanAInspect
Remove junk and fragment nodes from the knowledge graph.
CALL THIS when: search results are returning noise — short fragments like
"what", "only core", "memory" that clearly have no semantic value.
Run after a heavy ingestion session to keep the graph clean.
DO NOT call this obsessively. Run once every 50-100 ingestions, not after every ingest.
Over-cleaning removes nodes that are building blocks for relationships.
Removes nodes where:
- content length < min_content_length (default 15 chars)
- node has zero relationships AND zero semantic neighbors
- content is a single stopword with no context
Args:
min_content_length: Minimum characters for a node to survive. Default 15.| Name | Required | Description | Default |
|---|---|---|---|
| ctx | No | ||
| min_content_length | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description details removal criteria (three conditions) and default threshold. Lacks mention of destructiveness permanence or side effects.
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?
Compact and well-structured: summary, usage guidance, removal conditions, parameter explanation. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers removal criteria and usage frequency well. Missing details on return value and permanence of deletion, but adequate for the tool's simplicity.
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%, description explains only min_content_length with default and meaning. The ctx parameter is not described, leaving 50% of parameters 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?
Description clearly states 'Remove junk and fragment nodes from the knowledge graph', specifying verb and resource. Among siblings like suma_delete and suma_forget, it distinguishes itself as a cleanup tool for noise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call ('search results returning noise') and when not to ('not after every ingest', 'every 50-100 ingestions'), with rationale about over-cleaning.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
suma_coverageAInspect
State Verifier — 3-Tier QA Coverage for SQUAD Products.
SUMA Testing Manifesto (sealed April 13, 2026):
200 OK is not a test. It is a rumor.
Every write operation must be followed by a database assertion.
Every endpoint is a button. Every button must have a test.
MODES:
READ (default):
Returns coverage report from testframe_reports DB.
Classifies gaps by tier and severity.
Identifies "shallow" tests (status-code-only, no DB assertion).
GENERATE (mode="generate"):
Uses OPTION C: SUMA graph (WHY/WHAT) + your code_context (HOW)
Generates test scaffolds in 3 tiers:
- Component: endpoint isolation, UI element presence
- Technical: DB state verification after API calls (State Verifier pattern)
- Functional: end-to-end business workflow with all-layer assertions
Requires code_context (paste the relevant file/endpoint code).
The 3-Tier taxonomy:
component → Single endpoint or UI element in isolation
technical → Database state AFTER API call (State Verifier)
functional → Complete business workflow, all layers verified
The gap severity taxonomy:
missing → No test exists (CRITICAL)
not_implemented → Planned but not written (HIGH)
shallow → Test exists but only checks HTTP status, no DB assertion (HIGH)
flaky → Non-deterministic (HIGH)
skipped → Marked skip/todo (MEDIUM)
dead_end → Tests a UI element that no longer exists (LOW, cleanup)
Args:
product: Product to query (e.g. "squad-suma-mcp", "squad-qms", "squad-ghostgate").
If omitted in READ mode, returns all products.
area: Filter by test area (e.g. "auth", "ingest", "assign"). Optional.
mode: "read" (default) or "generate" (AI test generation via Option C).
tier_filter: Filter by test tier — "component", "technical", or "functional".
If omitted, all tiers returned.
decision_graph: Hierarchical Tech Questionnaire (REQUIRED for generate mode). Structure:
{
"platform": {
"type": "web|android|ios|api|robotics",
"framework": "React|Flutter|FastAPI|etc",
"auth_mode": "GhostGate|GoogleSSO|JWT|none"
},
"database": {
"engine": "postgresql|sqlite|none",
"orm": "prisma|sqlalchemy|none",
"target_table": "table_name"
}
}
code_context: Optional raw code string to test (UI components, API routes).
ingest_snapshot: If True, saves coverage state as a K-WIL graph node.
Returns (READ mode):
overall_coverage_pct, products[], gaps_by_tier, shallow_tests, recommendation
Returns (GENERATE mode):
component_tests[], technical_tests[], functional_tests[], manifesto_violations[]| Name | Required | Description | Default |
|---|---|---|---|
| ctx | No | ||
| area | No | ||
| mode | No | ||
| product | No | ||
| tier_filter | No | ||
| code_context | No | ||
| decision_graph | No | ||
| ingest_snapshot | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description fully covers behavioral traits: READ returns classified gaps and shallow tests, GENERATE produces scaffolds with manifesto violations. It also explains the state verifier pattern and required inputs like decision_graph and code_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?
The description is verbose, including a manifesto and taxonomy that could be more concise. While well-structured with headers, the agent may benefit from tighter focus on actionable instructions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, no output schema, no annotations), the description is thorough: defines modes, parameter roles, return structures, gap severity, and tier definitions. All necessary context for invocation is provided.
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 has 0% description coverage, but the description explains all 8 parameters with examples and default behavior (e.g., product defaults to all products in READ mode, decision_graph required for GENERATE). This adds substantial meaning beyond the bare 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?
Description clearly states the tool as 'State Verifier — 3-Tier QA Coverage for SQUAD Products' and explicitly defines two distinct modes (READ for coverage report, GENERATE for test scaffolds). This distinguishes it from sibling tools like suma_stats or suma_search.
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 details when to use READ vs GENERATE mode, including required context for GENERATE. It does not explicitly contrast with sibling tools, but the naming convention and focus on coverage versus other operations provide implicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
suma_deleteAInspect
Permanently delete nodes from the knowledge graph by node_id OR by source_doc.
Two modes — provide exactly one:
1. node_id mode — delete exactly one node:
Use suma_search first to find the node_id, then call suma_delete(node_id="...").
Use this when a specific fact is wrong or sensitive.
2. source_doc mode — delete an entire document's worth of nodes:
suma_delete(source_doc="resume_v2.pdf")
Erases ALL nodes ingested from that file. Use before re-uploading a corrected version.
This is the atomic document replacement operation — erase old, then re-ingest new.
Security: ALWAYS org-scoped. You cannot delete nodes that belong to another org.
Cascade: node_edges and orphaned entities are automatically cleaned up.
⚠️ IRREVERSIBLE. suma_export before calling if unsure.
CALL THIS when:
- User uploaded the wrong version of a PDF and wants to re-upload the correct one
- A specific node contains a factual error that cannot be corrected via suma_correct
- User explicitly asks to "delete", "remove", or "erase" a specific fact or document
DO NOT call this for noise cleanup — use suma_clean. That's for low-quality junk.
DO NOT call this speculatively — run suma_search first, confirm with user, then delete.| Name | Required | Description | Default |
|---|---|---|---|
| ctx | No | ||
| node_id | No | ||
| source_doc | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses key behaviors: irreversibility, org-scoped security, automatic cascade cleanup of edges and orphaned entities. Warns to use suma_export if unsure. No contradictions with annotations as none exist.
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 well-structured with a main purpose line followed by clear mode explanations, security notes, and usage guidelines. While lengthy, every sentence adds value. Some repetition (e.g., 'Permanently delete' in title and body) could be trimmed but does not detract significantly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (two deletion modes, security, side effects) and no output schema, the description covers purpose, modes, prerequisites, security, cascade behavior, irreversibility, and when to call alternatives. It is comprehensive for agent decision-making.
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 description explains that exactly one of node_id or source_doc should be provided and gives concrete usage examples. However, it does not mention the 'ctx' parameter from the schema, leaving it unexplained. With 0% schema coverage, the description compensates reasonably but not completely.
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 that the tool permanently deletes nodes by node_id or source_doc. It distinguishes itself from suma_clean (noise cleanup) and references suma_search for finding IDs, making the purpose highly specific and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly specifies when to call (wrong PDF, factual error, delete requests) and when not to (noise cleanup, speculative). Provides steps like using suma_search first and confirming with user. Clear alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
suma_docAInspect
Generate industry-standard documentation for any project using SUMA graph memory.
This tool does NOT fabricate. It retrieves real war stories, architecture rulings,
and deployment facts from the K-WIL graph, then uses Gemini to render them as
professional documentation. The graph IS the source of truth — suma_doc makes it readable.
Why this beats a generic doc generator:
Generic: "Here is how to install." (stateless, stale, hallucinated)
suma_doc: "We chose REST over MCP because [Architect Ruling Apr 5]. Here is how it works
in production: [real deployment from graph]. Avoid X — we tried it and [root cause]."
Args:
prompt: What documentation to generate. Be specific.
Examples:
"Write a README for the SUMA MCP Server API"
"Generate an ARCHITECTURE.md explaining the ring_search algorithm"
"Write a CHANGELOG entry for today's /api/wakeup deployment"
"Create an API reference for /api/ingest and /api/search"
"Write an onboarding guide for a new backend engineer joining the QMS team"
project: Optional filter to narrow graph search to a specific product.
Examples: "suma-mcp", "squad-qms", "squad-ghostgate", "squad-companion"
doc_type: Optional hint to shape output format.
"readme" → GitHub README with badges + sections
"architecture" → Design doc with decisions, trade-offs, diagrams description
"api_reference" → Endpoint table + request/response examples
"changelog" → Conventional Commits format, grouped by type
"onboarding" → Step-by-step guide for a new engineer
"runbook" → Ops runbook with commands, failure modes, escalation
If omitted, Gemini infers the best format from the prompt.
Returns:
document: The generated documentation (markdown)
nodes_used: Number of graph nodes retrieved as source material
source_summary: Brief description of what the graph provided
doc_type_detected: What format was generated| Name | Required | Description | Default |
|---|---|---|---|
| ctx | No | ||
| prompt | Yes | ||
| project | No | ||
| doc_type | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses key behaviors: the tool does not fabricate, retrieves real data from the K-WIL graph, and uses Gemini to render documentation. It makes the source of truth explicit and describes return fields. However, it omits potential side effects, auth requirements, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose and a clear how-it-works section, but it includes a promotional comparison paragraph ('Why this beats a generic doc generator') that adds length without essential functional information. The structure is logical but slightly verbose for an MCP tool description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description explains what is returned ('document', 'nodes_used', 'source_summary', 'doc_type_detected'). It covers the main parameters and the underlying mechanism. Missing are error scenarios, handling of missing graph data, and a description of the 'ctx' parameter. Still, it is fairly complete for a documentation generation 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 0%, so the description must add meaning. It details the 'prompt' parameter with examples, 'project' as optional filter with examples, and 'doc_type' with specific format options and descriptions. However, it fails to describe the 'ctx' parameter present in the schema. Overall, it adds substantial value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Generate industry-standard documentation for any project using SUMA graph memory' and explains how it retrieves real data from the K-WIL graph to produce documentation. It distinguishes itself from generic doc generators by emphasizing factuality and graph-based context, making its purpose specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides examples of prompts and documents types ('readme', 'architecture', etc.), implying when to use the tool, but it does not explicitly state when NOT to use it or suggest alternatives among sibling tools. Usage context is implied rather than explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
suma_edgesAInspect
Query relationships (edges) in the graph.
Use this to explore how entities are connected. Relationships have:
- emotional_valence: -1.0 (negative) to +1.0 (positive)
- evidence_node_id: The note that proves this relationship
- context_snippet: The sentence that established it
Args:
entity_id: Filter edges connected to this entity
relation_type: Filter by relationship type (e.g. "works_with", "created", "part_of")
min_valence: Only return edges with emotional_valence >= this value
limit: Max edges to return. Default 50.
Returns:
List of edges with their metadata.| Name | Required | Description | Default |
|---|---|---|---|
| ctx | No | ||
| limit | No | ||
| entity_id | No | ||
| min_valence | No | ||
| relation_type | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Describes read-only query behavior and details returned fields (emotional_valence, evidence_node_id, context_snippet). Does not mention side effects, auth requirements, or rate limits.
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?
Efficient and well-structured: purpose sentence, usage sentence, then bullet lists of returned fields and parameters. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description minimally states 'Returns: List of edges with their metadata' and earlier lists some fields. Could be more complete about default behavior, pagination, or output structure. Adequate but not thorough.
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 has 0% description coverage, but description includes an 'Args' section explaining four of five parameters (entity_id, relation_type, min_valence, limit) with meaningful context, e.g., min_valence: 'Only return edges with emotional_valence >= this value'. Missing ctx parameter explanation.
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 it queries relationships (edges) in the graph, with specific verb 'Query'. Distinguishes from sibling tools like suma_entities and suma_node by focusing on connections between entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage with 'Use this to explore how entities are connected', but does not explicitly state when not to use it or mention alternative tools. Lacks exclusions or context for siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
suma_entitiesAInspect
List all entities (Spheres) in the graph, sorted by gravitational mass.
FRACTAL ONTOLOGY: Every entity IS a sphere. Rajesh is a sphere, Work is a
sphere, iPhone 15 is a sphere. The only difference is gravitational mass
(degree = edge count) and flavor (entity_type).
Entity flavors: person, place, object, concept, event, organization, category
Args:
entity_type: Filter by flavor (e.g. "person", "concept", "category")
min_degree: Only return entities with at least this many connections
limit: Max entities to return. Default 50.
Returns:
List of entities with their metadata.| Name | Required | Description | Default |
|---|---|---|---|
| ctx | No | ||
| limit | No | ||
| min_degree | No | ||
| entity_type | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses sorting by gravitational mass, filtering, and default limit, but lacks details on sorting order (ascending/descending), pagination, and authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is mostly concise with a clear one-line summary, but the fractal ontology explanation adds verbosity that could be reduced or moved.
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 only vaguely states 'List of entities with their metadata' and does not specify return fields or pagination behavior, leaving gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds clear meaning for entity_type (lists flavors), min_degree (filter by connections), and limit (default 50). However, it does not explain the 'ctx' parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all entities (Spheres) sorted by gravitational mass, with filtering options. It distinguishes from siblings like 'suma_entity' (singular) and 'suma_search' via the ontological context.
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 context for when to use the tool (listing all entities with optional filters) but does not explicitly mention when not to use it or point to alternatives like 'suma_entity' for a single entity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
suma_entityBInspect
Query a specific entity (person, concept, place, etc.) from the graph.
Use this to answer "Who is X?" or "What is Y?" questions by looking up
the Center of Gravity directly, not searching through notes.
Args:
name: Entity name to look up (e.g. "Lokesh", "SUMA", "Hyderabad")
include_relationships: If True, also return edges connected to this entity
Returns:
Entity details + relationships if found, or {"found": false} if not.| Name | Required | Description | Default |
|---|---|---|---|
| ctx | No | ||
| name | Yes | ||
| include_relationships | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool is a read operation returning entity details or a 'found: false' response, but does not mention any additional behavioral traits such as authorization requirements, rate limits, or side effects.
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 follows a docstring style with Args and Returns sections, which is structured. However, it is somewhat verbose and could be more concise. It is acceptable but not optimally tight.
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 and no annotations, the description explains the purpose and basic return format but does not address edge cases, error handling, or the undocumented 'ctx' parameter. It is moderately complete for a simple query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% parameter description coverage. The description adds basic meaning for 'name' and 'include_relationships', but completely omits the 'ctx' parameter. This partial coverage is insufficient for a tool with multiple 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 queries a specific entity from the graph for 'Who is X?' questions, distinguishing it from searching through notes. However, it does not differentiate from siblings like suma_entities or suma_search, which might perform similar lookups.
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 indicates when to use (for direct entity lookups) and implies not for searching notes, but it does not explicitly name alternative tools or state when not to use. This is adequate but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
suma_exportAInspect
Export the knowledge graph as structured JSON.
Use this to:
- Migrate data from Docker local to Cloud SUMA
- Back up your graph before a wipe
- Share a graph between machines (export → suma_import on other machine)
- Satisfy GDPR data portability requests ("download my data")
Returns nodes, relationships, and graph metadata.
The output can be passed directly to suma_import on another SUMA instance.
Args:
sphere: If provided, only export nodes in this sphere (e.g. "architecture", "personal").
offset: Skip the first N nodes — use for pagination on large graphs.
limit: Max nodes to return per call. Default 500 to avoid context window overflow.| Name | Required | Description | Default |
|---|---|---|---|
| ctx | No | ||
| limit | No | ||
| offset | No | ||
| sphere | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explains pagination (offset/limit), default limit of 500 to avoid context overflow, and that the output is JSON with nodes, relationships, and metadata. However, it does not explicitly state read-only behavior or potential side effects.
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 efficient: a clear opening sentence, bullet-list use cases, return info, and parameter explanations. Every sentence adds value, and the structure is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is largely complete for an export tool with pagination and a sibling import tool. It covers purpose, parameters, and output structure (nodes, relationships, metadata). Missing explanation of the ctx parameter prevents a perfect score.
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 has 0% description coverage, but the description's 'Args' section explains sphere, offset, and limit, adding meaning beyond names and types. The ctx parameter is not explained, leaving a minor gap.
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 starts with 'Export the knowledge graph as structured JSON,' providing a clear verb and resource. It lists specific use cases (migrate, backup, share, GDPR) that distinguish it from siblings like suma_import (import) and suma_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly enumerates when to use the tool (data migration, backup, sharing, GDPR). It implies the alternative (suma_import for importing) but does not include explicit when-not-to-use or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
suma_forgetAInspect
Permanently delete a node (or all nodes matching a keyword) from the knowledge graph.
⚠️ THIS IS IRREVERSIBLE. Run suma_export before calling this if you are unsure.
CALL THIS when:
- A specific fact is wrong and needs to be removed (use node_id mode)
- A person invokes GDPR "right to be forgotten" (use keyword mode)
- You confirmed with the user they want something permanently erased
DO NOT call this to "tidy up" — use suma_clean for noise removal.
suma_forget is for intentional, confirmed permanent deletion only.
Two modes:
1. node_id: deletes exactly one node + all its edges. Use suma_search first to find the ID.
2. keyword: deletes ALL nodes whose content contains the keyword (GDPR erasure).
Args:
node_id: Exact node ID to delete (get this from suma_search results first).
keyword: Delete all nodes containing this string (case-insensitive). GDPR mode.
scrub_logs: Also delete from usage_log. Default True — required for GDPR compliance.| Name | Required | Description | Default |
|---|---|---|---|
| ctx | No | ||
| keyword | No | ||
| node_id | No | ||
| scrub_logs | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description provides full behavioral transparency: it warns deletion is irreversible, deletes all edges, explains two modes, and notes scrub_logs default for GDPR compliance.
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 well-structured with sections and front-loaded warnings, but slightly lengthy. Most sentences add value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema or annotations, and the description covers main points but lacks explanation of return values and the ctx parameter, leaving gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% coverage, but the description explains node_id, keyword, and scrub_logs well. However, it misses explaining the ctx parameter, so not fully comprehensive.
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 permanently deletes a node or nodes matching a keyword from the knowledge graph, and distinguishes it from sibling tools like suma_clean for tidying up.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly lists when to call (specific fact wrong, GDPR right to be forgotten, user confirmed permanent erasure) and when not to call (for tidying up, use suma_clean instead), with a warning to export first if unsure.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
suma_importAInspect
Import nodes (and optionally edges) into the knowledge graph.
Use this to:
- Restore a graph from suma_export output
- Sync data from Docker local to Cloud (export on Docker → import to Cloud)
- Migrate between machines
Args:
nodes: List of node dicts — each must have "id", "content", "sphere".
Copy directly from suma_export output.
edges: Optional list of edge dicts — each has "source", "target", "relationship".
merge: If True (default), add to existing graph. If False, replaces — use with caution.| Name | Required | Description | Default |
|---|---|---|---|
| ctx | No | ||
| edges | No | ||
| merge | No | ||
| nodes | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It reveals that merge=True (default) adds to existing graph, while merge=False replaces it, and warns about caution. It also specifies node format requirements (id, content, sphere). However, it does not explicitly state if the operation is destructive (despite the replacement warning) or idempotent.
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 well-structured with clear bullet points and separate sections. It is concise, every sentence adds value, and it front-loads the purpose before detailing parameters. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers the tool's key aspects: purpose, usage, parameter semantics, and a critical merge warning. It could be improved by mentioning return values (e.g., success or failure indication) or idempotency, but for a 4-parameter import tool with merge logic, this is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It explains three of four parameters: nodes (list with required fields id, content, sphere), edges (optional list with source, target, relationship), and merge (boolean with default true). The ctx parameter is not described, but the description adds significant meaning beyond the schema for the main 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 imports nodes and optionally edges into the knowledge graph. It specifies the verb 'Import' and resource 'nodes (and optionally edges) into the knowledge graph', and distinguishes from sibling tools like suma_export and suma_clean by listing specific use cases: restore, sync, migrate.
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 explicit when-to-use scenarios: restore from export, sync Docker to Cloud, migrate between machines. It also warns about the merge parameter replacing the graph when set to False. However, it does not specify when not to use the tool, though the sibling tool list implies alternatives for specific operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
suma_ingestAInspect
Add new information to the SUMA knowledge graph.
[SYSTEM INSTRUCTION — QUALITY GATE: ASK BEFORE YOU INGEST]:
You are the cognitive processor. Before calling this tool, ask yourself ONE question:
"Would a new engineer reading this in 6 months understand something meaningful and act on it?"
If YES → ingest. If NO → do not ingest.
✅ INGEST (signal):
- Architectural decisions and rulings ("We chose REST over GraphQL because...")
- Bugs encountered and their root cause ("asyncio.run() in daemon thread killed by Cloud Run")
- Features shipped with build numbers ("Build 83: Active Sleep daemon live")
- Business decisions and pivots ("Switched to B2B SaaS model April 2026")
- People, relationships, credentials location ("Sharath is org_id=10, enterprise tier")
- Vision statements ("SUMA is the memory layer for all AI tools, not just an app")
❌ DO NOT INGEST (noise):
- Raw sensor data (joint angles, GPS coords, temperature readings)
- Presence/motion events ("Person at 22:57:22", "Person left 22:57:36")
- Intermediate debugging steps that didn't lead to a fix
- Timestamps, log lines, stack traces verbatim
- File contents, code blobs, PDF text (summarize instead)
- Anything that will be irrelevant or stale in 30 days
- Repetitive status updates without new information ("still running", "still testing")
- The current conversation context itself (that's what the chat window is for)
[GRAPH VS BLOB ARCHITECTURE]:
Do NOT pass raw massive text verbatim. Extract the semantic gist.
If the user uploads a file, inject a pointer node: "Blueprint for X exists. Core keywords: Y, Z. Path: [URL]"
[EXPLICIT INGESTION TRIGGER]:
If the user includes #memory or #sumamemory anywhere, IMMEDIATELY call suma_ingest with the core facts. No quality gate for explicit commands — user intent is absolute law.
[NODE NAMING]: Always name entities using [System]_[Component]_[Status] format
(e.g., ETL_Delta_Error, App_Login_Success, API_Auth_Fixed).
[ALLOWED SPHERES]: architecture, debugging, work, personal, family, health, friends
(new spheres auto-registered if needed — keep it minimal).
[RELATIONSHIP VERBS]: Use these universal primitives only:
DEPENDS_ON, IMPLEMENTS, MANAGES, BUILT_BY, USES, HAS_ISSUE,
COMMUNICATES_WITH, FUNDED_BY, LEADS, WORKS_AT, DEPLOYED_TO, RESOLVES
Args:
text: The compressed, synthesized information you generated to be stored.
sphere: Which sphere to store in. Default "default" (auto-classified by Nano-Router).
extract_relationships: Auto-extract relationships from text. Default True.| Name | Required | Description | Default |
|---|---|---|---|
| ctx | No | ||
| text | Yes | ||
| sphere | No | default | |
| extract_relationships | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description does the heavy lifting. It discloses that the tool compresses and synthesizes input (graph vs blob architecture), injects pointer nodes for file uploads, and uses predefined relationship verbs. However, it omits details about idempotency, authentication, rate limits, or what happens on duplicate ingestion.
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 excessively long (multiple paragraphs with subheadings) and includes many system-level instructions that could be in a separate prompt or documentation. While structured, it loads the tool description with rules that reduce scanability. A shorter version focusing on purpose and key guidelines would be more effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, no output schema, many siblings), the description covers purpose, usage rules, behavioral traits (compression, relationship extraction), and formatting conventions. It lacks information about the return value or error handling, but for an AI agent to decide when and how to call it, the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description explains three of four parameters: 'text' (compressed synthesized information), 'sphere' (default auto-classified), and 'extract_relationships' (auto-extract). The 'ctx' parameter is not mentioned. The description also provides additional context on how to format the 'text' value (node naming, allowed spheres), adding value 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 opens with 'Add new information to the SUMA knowledge graph,' providing a clear verb and resource. It further differentiates from sibling tools by detailing what qualifies as 'signal' vs 'noise,' which implicitly distinguishes from other suma_* tools that may focus on cleaning, deletion, or 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?
The description explicitly defines when to use the tool (e.g., architectural decisions, bugs, features) and when not to (e.g., raw sensor data, log lines). It includes a quality gate question and an explicit trigger (#memory / #sumamemory) that bypasses the gate. Alternative actions are implied through the DO NOT INGEST list, which clarifies what other tools (like summarization) might be used for.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
suma_nodeAInspect
Get a specific node from the SUMA knowledge graph with its weight profile.
Returns the node's content, metadata, emotional weight, graph
centrality, and all connected neighbor nodes.
Args:
node_id: The node ID to look up (e.g., "SHARATH", "ACCENTURE")
include_neighbors: Include connected nodes. Default True.
include_weight_profile: Include harmonic weight analysis. Default True.| Name | Required | Description | Default |
|---|---|---|---|
| ctx | No | ||
| node_id | Yes | ||
| include_neighbors | No | ||
| include_weight_profile | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It explains return content and arguments but does not mention read-only nature, permissions, or side effects. It is adequate but not explicit.
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?
Concise and well-structured: purpose first, then return fields, then arguments. Every sentence adds value, no 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?
With no output schema, the description lists return fields, giving the agent a good picture. It could add error handling or edge cases, but is sufficient for a retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, requiring description to explain parameters. It describes three of four parameters (node_id, include_neighbors, include_weight_profile) with examples and defaults, but omits 'ctx' entirely, leaving its meaning unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a specific node from the SUMA knowledge graph with its weight profile, listing returned fields. It distinguishes from siblings like suma_edges and suma_entity.
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 does not specify when to use this tool over alternatives like suma_entity or suma_edges. Usage is implied but no when-not-to-use or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
suma_patternsAInspect
Find K-WIL algorithm patterns — hidden connections in the knowledge graph.
Detects repeated behaviors, temporal patterns, and cross-pattern
causation (e.g., "stress_sunday CAUSES arguments_monday").
Args:
query: Topic or keyword to find patterns for
include_cross_patterns: Also detect cross-pattern causation. Default True.| Name | Required | Description | Default |
|---|---|---|---|
| ctx | No | ||
| query | Yes | ||
| include_cross_patterns | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes detection behavior but does not explicitly state it is read-only, nor does it detail side effects or limitations. Adequate but lacks depth.
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 purpose, no fluff. Example included efficiently. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists; description does not mention return format. It explains the tool's function adequately but lacks information on what the agent receives after invocation. Adequate for a simple pattern search but not comprehensive.
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 description must compensate. It explains 'query' and 'include_cross_patterns' with examples and defaults, but the 'ctx' parameter is completely undocumented. Partial value added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool finds K-WIL algorithm patterns, detecting repeated behaviors, temporal patterns, and cross-pattern causation, with an example. This distinguishes it from siblings like suma_search (general search) or suma_stats (statistics).
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 vs alternatives. The description implies usage for pattern detection but does not contrast with siblings like suma_search or suma_edges, nor does it specify when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
suma_pingAInspect
[STEP 1 OF 3 — CALL THIS FIRST, ALWAYS, BEFORE ANY OTHER TOOL]
Verifies your MCP connection, org_id, and Bearer token are valid.
If this fails, no other tool will work — stop and fix the connection.
THE 3-STEP PROTOCOL every agent must follow in every session:
1. suma_ping() → confirm connection (you are here)
2. suma_wakeup() → inject zero-shot context for this developer
3. suma_search() → retrieve before you answer ANYTHING
Do NOT skip to suma_search or suma_ingest without calling this first.
A session with no suma_ping is a session flying blind.
Returns: server version, org_id, tier, weight_profile, timestamp.| Name | Required | Description | Default |
|---|---|---|---|
| ctx | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description fully discloses that failure means no other tool works and lists return fields. Provides sufficient behavioral context for a read-only ping operation.
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?
Well-structured with step numbering and emphasis, but slightly verbose. Front-loaded with purpose, efficiently conveying critical protocol.
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?
Complete for a simple ping tool: covers purpose, mandatory usage, and return values. The only missing element is the undocumented ctx parameter, which is minor given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter (ctx) with 0% coverage, and the description provides no explanation of what ctx does or its usage. This is a significant gap.
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 verifies MCP connection, org_id, and Bearer token, and positions itself as the mandatory first step. This distinguishes it from siblings like suma_wakeup and suma_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs 'CALL THIS FIRST, ALWAYS, BEFORE ANY OTHER TOOL' and outlines the 3-step protocol. Clearly warns not to skip to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
suma_searchAInspect
[STEP 3 OF 3 — CALL THIS BEFORE ANSWERING ANY ARCHITECTURE OR PROJECT QUESTION]
THE GOLDEN RULE: Never answer from training data alone when SUMA is connected.
If the user asks ANYTHING about architecture, code decisions, bug history,
business context, or people — call suma_search FIRST, answer SECOND.
WHY: Training data is frozen at a cutoff date. SUMA holds live project truth —
what was decided last week, what failed last month, who owns what right now.
Answering without searching is guessing. Guessing wastes the developer's time.
WHEN TO CALL:
✅ "How does auth work in this project?" → search first
✅ "What did we decide about the database schema?" → search first
✅ "Who is Sharath?" → search first
✅ "Why are we using gRPC instead of REST?" → search first
❌ "What is 2+2?" → skip (factual, not project-specific)
❌ "Format this JSON" → skip (task, no project context needed)
SINGLE-WORD / FILE QUERIES:
If the user types a single word or filename (e.g., "auth.py", "scripts", "billing"):
DO NOT blindly throw the single word into suma_search. First, clarify your intent:
1. Is this a file? (Use directory/file tools to look at it first, or ask the user what they want to know about it).
2. Is this a folder? (Use directory tools to list its contents).
3. Is this a concept? (Formulate a complete natural language question like "What is the billing architecture?" instead of just searching "billing").
4. If unsure, ask the user: "Are you referring to the file/folder, or do you want me to search the memory graph for concepts related to it?"
VECTOR NAMESPACING:
- Default: hardware/telemetry excluded (prevents "Sphere" vocabulary collision)
- sphere="robotics" → search only Mr. Chunky / hardware memory
- sphere="all" → search everything including hardware
- Omit sphere → general project knowledge (correct for 95% of queries)
Args:
query: What to search for (natural language — be specific)
similarity_threshold: Minimum match quality. Default 0.65 (lower = more results, less precise).
circuit_breaker: Max results returned. Default 8 (memory protection).
depth: Graph traversal depth. 1=direct hits, 2=multi-hop (default), 3=deep exploration.
sphere: Domain filter. "robotics" for hardware, "all" for everything, omit for general.
sentiment: Filter by sentiment — "positive", "negative", "mixed", or None.| Name | Required | Description | Default |
|---|---|---|---|
| ctx | No | ||
| depth | No | ||
| query | Yes | ||
| sphere | No | ||
| sentiment | No | ||
| circuit_breaker | No | ||
| similarity_threshold | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description reveals key behaviors: vector/graph search, default exclusion of hardware/telemetry, parameter effects (similarity_threshold, depth, circuit_breaker), and sentiment filtering. Missing an explicit statement about being read-only, but it's implied.
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 verbose with emphatic formatting (STEP 3 OF 3, GOLDEN RULE) and repeated emphasis. It is well-organized into sections but could be trimmed to essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, yet the description does not specify what the search returns (e.g., list of nodes, scores). It covers input parameters well but omits return format and ordering, leaving some ambiguity for a complex 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?
With 0% schema coverage, the description compensates by explaining all parameters except 'ctx'. Each parameter's purpose, default, and effect (e.g., lower similarity_threshold yields more results) is described, though 'ctx' remains 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?
Clearly states it is a search tool for project-specific knowledge, distinct from other SUMA tools. The golden rule emphasizes calling it before answering architecture or project questions, making its purpose unmistakable.
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?
Provides explicit when-to-call examples with checkmarks and cross marks, handles single-word/filename queries with clear steps, and explains sphere defaults and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
suma_statsAInspect
Return graph statistics and shadow telemetry for this org.
Use this to show the user their ROI receipt — how many tokens SUMA saved them this month vs lifetime. Also returns graph health metrics.
Returns node count, edge count, spheres breakdown, queries used, tokens saved this month, and tokens saved lifetime. No arguments needed — reads from the authenticated org.
| Name | Required | Description | Default |
|---|---|---|---|
| ctx | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It states the tool returns data (implies read-only) and reads from authenticated org. However, it does not explicitly state it is non-destructive or safe, leaving room for ambiguity. The description is adequate but could be more explicit.
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 concise with four sentences, front-loading the purpose and then listing return values. No unnecessary words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (stats retrieval) and lack of output schema, the description fully lists what is returned (node count, edge count, tokens saved, etc.), making it self-contained. No additional information needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one undocumented parameter 'ctx'. The description adds value by stating 'No arguments needed', clarifying that the parameter is not required and the tool works without input. This goes beyond the schema's empty description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns graph statistics and shadow telemetry, specifying the exact data returned. It distinguishes itself from sibling tools (e.g., suma_clean, suma_delete) by focusing on stats and ROI receipt.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use it to show the user their ROI receipt and notes that no arguments are needed, implying a simple query. While it doesn't mention when not to use it, the context is clear given the sibling tools have different purposes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
suma_summaryAInspect
Return a synthesized Markdown knowledge dump for a specific topic sphere.
Call suma_topics() first to discover topic names, then call this with one
of those topic names to get the full chronological history for that sphere.
Args:
topic: Sphere name from suma_topics() (e.g. "architecture", "health").
If omitted, returns ALL nodes (may be very large).
limit: Max nodes to return per topic. Default 50.
Returns: { topic, node_count, markdown: "# Topic\n\n..." }| Name | Required | Description | Default |
|---|---|---|---|
| ctx | No | ||
| limit | No | ||
| topic | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry burden. Discloses large output when topic omitted and mentions limit default, but lacks details on error handling, auth, or rate limits.
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?
Very concise: first sentence states purpose, then usage guidance, then parameter details. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers basic usage, but missing ctx parameter explanation, error scenarios, and any performance or auth context. Adequate but with notable gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Describes topic and limit parameters well (source, defaults, effect of omission). However, ctx parameter is completely undocumented, and schema coverage is 0%, leaving a gap.
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 'synthesized Markdown knowledge dump for a specific topic sphere,' with specific verbs and resource. It distinguishes from siblings like suma_topics by indicating prerequisite usage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance to call suma_topics first and then use a discovered topic name. Also notes what happens if topic is omitted. Lacks explicit 'when not to use' but provides strong context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
suma_talkAInspect
Bidirectional memory — retrieves context AND ingests the refined insight in one call.
USE THIS INSTEAD OF suma_search when:
- The conversation is ongoing and you want SUMA to learn from this exchange too
- You need both retrieval AND storage in one round-trip (saves one tool call)
- The user is sharing something personal, reflective, or relationship-related
USE suma_search instead when:
- You only need to retrieve — you are NOT learning anything new from this query
- You want precise vector search control (threshold, depth, sphere filters)
DO NOT pass raw logs, file contents, or code blobs here.
Distill what the user is actually communicating — the behavioral intent, the decision,
the feeling — and pass that refined insight. SUMA learns from meaning, not syntax.
Args:
message: The distilled behavioral intent of the user (not raw text — synthesize first).
persona: Response style — "companion", "analyst", "mentor", etc. Default "companion".| Name | Required | Description | Default |
|---|---|---|---|
| ctx | No | ||
| message | Yes | ||
| persona | No | companion |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description explains the bidirectional nature, need for distilled insight, and that SUMA learns from meaning. It does not mention destructive actions or auth needs, but effectively conveys behavioral traits beyond 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?
The description is well-structured with sections, bullet points, and a warning. It is concise yet covers all key aspects without verbosity.
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 and no annotations, the description adequately covers purpose, usage, parameters, and behavioral guidelines. It explains return format is context, but does not detail fields. Overall sufficient for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%. The description adds meaning to 'message' (distilled intent, not raw text) and 'persona' (response style examples). However, 'ctx' parameter is not described, leaving a gap.
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 defines the tool as bidirectional memory that retrieves context and ingests refined insight in one call. It uses specific verbs and distinguishes from siblings like suma_search (retrieval only).
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 explicit when-to-use and when-not-to-use guidelines, including scenarios for this tool vs suma_search. It also warns against passing raw logs or code blobs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
suma_topicsAInspect
Return a lightweight Table of Contents of the user's knowledge graph.
Clusters nodes by sphere, counts them, and returns the top topics
ranked by node count (centrality proxy). Use this before suma_summary
to discover which topics exist — then drill into one.
Returns: { topics: [{sphere, node_count, sample_ids}], total_nodes }| Name | Required | Description | Default |
|---|---|---|---|
| ctx | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description transparently explains the tool clusters nodes by sphere, counts them, and returns ranked topics. It implies a read-only, lightweight operation without side effects.
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 concise with no superfluous words. It front-loads the purpose and efficiently uses three short paragraphs to convey use case, behavior, and output format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one optional parameter, and the description explains the output structure well. However, the lack of explanation for 'ctx' leaves a notable gap, preventing full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'ctx' is not explained in the description, and schema description coverage is 0%. The description must compensate for low coverage but does not, leaving agents uninformed about what 'ctx' controls.
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 'Return a lightweight Table of Contents of the user's knowledge graph' with a specific verb and resource. It further differentiates from siblings by advising use before suma_summary to discover topics.
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?
Provides explicit guidance to use this tool before suma_summary to discover topics and then drill into one. While it doesn't list exclusions, the context is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
suma_wakeupAInspect
[STEP 2 OF 3 — CALL THIS IMMEDIATELY AFTER suma_ping, BEFORE SPEAKING]
Injects zero-shot context for this developer — their assigned tickets,
recent high-priority work, open architectural decisions, and active blockers.
Prepend this output to your very first response so the developer never has
to repeat themselves. They walk in and SUMA already knows where they left off.
DO NOT skip this step to "save tokens." One suma_wakeup call (≈120 tokens)
prevents the developer from wasting 10 minutes re-explaining context.
QMS Integration: When tickets are assigned in squad-qms, QMS fires a silent
webhook to SUMA. Those nodes accumulate in the K-WIL graph. This tool
surfaces the highest-gravity ones for the connecting user.
Args:
user_name: Developer's name (e.g. "Nagesh Anna"). Used to find assigned tickets.
user_email: Developer's email. Used as fallback identity if name not provided.
Returns:
assigned_tickets: High-gravity work nodes assigned to this user
recent_context: Recent architectural decisions and work context for the org
greeting_context: Formatted string ready to prepend into Claude's system prompt| Name | Required | Description | Default |
|---|---|---|---|
| ctx | No | ||
| user_name | No | ||
| user_email | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool modifies the conversation by prepending context to the agent's response, and returns specific structured data. It does not mention potential side effects on SUMA storage, but the non-destructive, read-like behavior is implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the critical step order and purpose, followed by structured argument and return value lists. It is slightly verbose with QMS integration details, but every sentence adds context. Could be trimmed for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations or output schema, the description covers purpose, usage sequence, and return values. However, it omits the 'ctx' parameter, error handling, and idempotency guarantees, leaving incomplete context for a multi-parameter 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 0%, but the description explains two of three parameters (user_name, user_email) with usage details and fallback behavior. However, the 'ctx' parameter (with default null) is not described, leaving a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: injecting zero-shot context after suma_ping. It specifies the verb ('injects context') and resource ('developer's assigned tickets, recent work'), and distinguishes it from siblings by positioning it as step 2 of a 3-step sequence.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to call it ('immediately after suma_ping, before speaking') and warns against skipping to save tokens, explaining the cost-benefit. It does not explicitly state when not to use it, but the mandatory nature is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
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
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.
Discussions
No comments yet. Be the first to start the discussion!