suma-memory

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes what gets removed (nodes based on content length, relationships, and stopwords), the operational context (after ingestion sessions), and usage constraints (frequency limits to prevent over-cleaning). However, it lacks details on error handling or performance characteristics like 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 well-structured and front-loaded with the core purpose, followed by usage guidelines and parameter details. Every sentence adds value without redundancy, making it efficient and easy to parse for an AI agent.

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 (a mutation operation with no annotations or output schema), the description does a good job covering purpose, usage, and some behavioral aspects. However, it lacks details on the return value or error conditions, which are important for a tool that modifies the knowledge graph.

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 the 'min_content_length' parameter's purpose and default value, adding meaningful context beyond the schema. However, it does not address the 'ctx' parameter, leaving one of the two parameters undocumented in the 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's purpose: 'Remove junk and fragment nodes from the knowledge graph.' It specifies the verb ('Remove') and resource ('junk and fragment nodes'), and distinguishes it from siblings like suma_ingest or suma_search by focusing on cleanup rather than ingestion or querying.

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 guidance on when to use ('CALL THIS when: search results are returning noise... Run after a heavy ingestion session') and when not to ('DO NOT call this obsessively... not after every ingest. Over-cleaning removes nodes that are building blocks'). It also implies alternatives by referencing other tools like search, though it doesn't name specific siblings.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's two operational modes, their outputs, and specific requirements (e.g., 'decision_graph' required for generate mode). It also mentions the 'ingest_snapshot' parameter's effect of saving coverage state. However, it doesn't address potential side effects like performance impact or error conditions, leaving some behavioral aspects unclear.

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 sections (manifesto, modes, taxonomies, args, returns) and front-loads the core purpose. However, it includes some verbose elements like the manifesto text and detailed taxonomy explanations that, while informative, could be more concise. Most sentences earn their place by providing essential context.

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 complex tool with 8 parameters, 0% schema coverage, no annotations, and no output schema, the description provides exceptional completeness. It covers purpose, usage modes, parameter semantics, return formats for both modes, and contextual taxonomies. The description fully compensates for the lack of structured metadata, making the tool's functionality clear and actionable.

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?

Given 0% schema description coverage, the description fully compensates by providing detailed semantic explanations for all parameters. It explains 'product' filtering, 'area' filtering, 'mode' options with their implications, 'tier_filter' options, 'decision_graph' structure and requirements, 'code_context' purpose, and 'ingest_snapshot' functionality. The description 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 the tool's purpose: 'State Verifier — 3-Tier QA Coverage for SQUAD Products.' It specifies the verb ('verify' through coverage analysis) and resource ('SQUAD Products'), and distinguishes itself from siblings by focusing on test coverage analysis and generation rather than cleaning, documentation, or other operations listed in the sibling tools.

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

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

The description explicitly defines when to use different modes: READ mode for retrieving coverage reports and GENERATE mode for creating test scaffolds. It provides clear context for each mode's purpose and requirements, such as needing 'code_context' for GENERATE mode and specifying that 'decision_graph' is REQUIRED for generate mode, offering comprehensive guidance on tool usage.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: it 'does NOT fabricate,' retrieves data from the 'K-WIL graph,' uses 'Gemini to render,' and treats the graph as the 'source of truth.' It also implies a multi-step process (retrieve, then render). However, it lacks details on potential limitations like rate limits, authentication needs, or error handling, which would be valuable for a tool with no annotation coverage.

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 and front-loaded with the core purpose, followed by differentiation, parameter details, and return values. Most sentences earn their place by adding value, such as contrasting with generic tools or explaining parameter nuances. However, some sections like the 'Why this beats...' example could be slightly condensed without losing clarity, keeping it efficient but not maximally concise.

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 annotations, no output schema), the description does an excellent job of completeness. It covers purpose, differentiation, parameter semantics, and return values in detail. The only gap is the lack of an output schema, but the description compensates by documenting return fields ('document', 'nodes_used', etc.). For a tool with no structured metadata, this is highly complete, though not perfect without explicit error or edge-case handling.

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 fully compensate. It provides detailed semantics for all parameters: 'prompt' with examples and guidance to 'Be specific,' 'project' as an 'Optional filter to narrow graph search' with examples, and 'doc_type' as an 'Optional hint to shape output format' with enumerated options and default behavior. This adds substantial meaning beyond the bare schema, fully documenting parameter purposes and usage.

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: 'Generate industry-standard documentation for any project using SUMA graph memory.' It specifies the verb ('generate'), resource ('documentation'), and mechanism ('using SUMA graph memory'), distinguishing it from generic documentation generators. The 'Why this beats a generic doc generator' section further differentiates it from siblings by emphasizing its reliance on real graph data rather than fabrication.

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 guidance on when to use this tool vs. alternatives. It contrasts suma_doc with 'generic doc generators' that are 'stateless, stale, hallucinated,' while suma_doc retrieves 'real war stories, architecture rulings, and deployment facts.' This clearly indicates when to prefer suma_doc (for accurate, graph-based documentation) and when not to (for fabricated or generic content).

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context beyond the schema: it describes the structure of relationships (emotional_valence, evidence_node_id, context_snippet) and the default limit behavior. However, it doesn't cover critical aspects like error handling, authentication needs, rate limits, or whether it's read-only (implied by 'query' but not explicit). This leaves gaps for a tool with 5 parameters.

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 appropriately sized and front-loaded: it starts with the core purpose, then usage context, relationship details, and parameter explanations in a structured 'Args' and 'Returns' section. Every sentence adds value, with no wasted words. Minor improvement could be making the 'ctx' parameter explanation clearer, but overall it's efficient.

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 (5 parameters, no annotations, no output schema), the description is moderately complete. It covers the purpose, usage, relationship structure, and parameters well, but lacks details on behavioral aspects like error handling, pagination, or return format specifics (beyond 'List of edges with their metadata'). For a query tool with multiple filters, more context on limitations or examples would enhance 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 description adds significant meaning beyond the input schema, which has 0% description coverage. It explains all 5 parameters: entity_id filters by entity, relation_type by relationship type, min_valence by emotional threshold, limit sets max returns, and implies ctx is for context (though less clearly). This compensates well for the schema's lack of descriptions, providing clear semantics for each 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's purpose: 'Query relationships (edges) in the graph' and 'explore how entities are connected.' It specifies the verb ('query') and resource ('relationships/edges'), distinguishing it from siblings like suma_entities (likely about entities) or suma_search (likely broader search). However, it doesn't explicitly contrast with all siblings, such as suma_node (which might query nodes rather than edges).

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 implied usage context: 'Use this to explore how entities are connected.' This suggests it's for relationship discovery, but it lacks explicit guidance on when to use this tool versus alternatives like suma_entities (for entities) or suma_search (for general search). No exclusions or specific prerequisites are mentioned, leaving some ambiguity for the agent.

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

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

With no annotations provided, the description carries the full burden. It explains that entities are sorted by 'gravitational mass' (defined as edge count) and lists entity flavors, adding useful context beyond basic listing. However, it lacks details on permissions, rate limits, pagination, or error handling, which are important for a tool with filtering and 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 well-structured with clear sections (purpose, ontology, parameters, returns) and uses bullet points for readability. It's appropriately sized but could be slightly more concise by integrating the fractal ontology explanation more tightly with the purpose statement.

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 and no output schema, the description does a fair job: it explains the tool's purpose, parameters, and return type ('List of entities with their metadata'). However, it lacks details on output format, error cases, or behavioral constraints like rate limits, leaving gaps for a tool with filtering and sorting logic.

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. It fully documents all 4 parameters: 'entity_type' (with examples and flavor list), 'min_degree' (explained as connection count), and 'limit' (with default). It also clarifies that 'gravitational mass' equals 'degree = edge count', adding semantic meaning not in the schema.

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

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

The description clearly states the tool's purpose: 'List all entities (Spheres) in the graph, sorted by gravitational mass.' It specifies the verb ('List'), resource ('entities/Spheres'), and sorting criterion. However, it doesn't explicitly differentiate from sibling tools like 'suma_entity' or 'suma_search', which prevents a perfect score.

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 no guidance on when to use this tool versus alternatives. It mentions filtering parameters but doesn't compare to sibling tools like 'suma_search' or 'suma_entity', nor does it specify prerequisites or exclusions. This leaves the agent without context for tool selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: it performs a read-only lookup (implied by 'Query'), returns entity details with optional relationships, and specifies the return format including a 'found' flag for missing entities. However, it lacks details on error handling, rate limits, or authentication needs, leaving some 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 front-loaded with the core purpose, followed by usage guidelines, parameter details, and return values in a logical flow. Every sentence earns its place, with no wasted words, making it efficient and easy to parse for an agent.

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 moderate complexity (3 parameters, no output schema, no annotations), the description is largely complete. It covers purpose, usage, parameters, and returns adequately. However, it lacks details on error cases beyond 'not found', and the undocumented 'ctx' parameter leaves a minor gap in full context.

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. It adds meaningful semantics for both parameters: 'name' is explained with examples (e.g., 'Lokesh'), and 'include_relationships' clarifies its effect ('also return edges'). The 'ctx' parameter is undocumented, but the two documented parameters are well-explained, providing good coverage overall.

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 with specific verbs ('Query', 'look up') and resources ('specific entity from the graph'), distinguishing it from siblings like 'suma_search' (which searches notes) and 'suma_entities' (likely lists entities). It explicitly contrasts with 'searching through notes' to highlight its direct lookup function.

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 guidance on when to use this tool ('to answer "Who is X?" or "What is Y?" questions') and when not to ('not searching through notes'), with a clear alternative implied ('searching through notes' likely refers to 'suma_search'). This helps the agent choose between direct entity lookup and broader search methods.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: it exports data (implying read-only, non-destructive operation), mentions pagination for large graphs via offset/limit, warns about context window overflow with a default limit of 500, and specifies the output format (JSON). However, it doesn't cover potential errors, rate limits, or authentication needs, leaving some 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 well-structured and front-loaded: it starts with the core purpose, followed by usage guidelines in a bulleted list, return value explanation, and parameter details. Every sentence adds value without redundancy, 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?

Given no annotations and no output schema, the description does an excellent job covering purpose, usage, parameters, and output format. However, it lacks details on error handling, performance constraints, or exact JSON structure, which could be helpful for a tool with 4 parameters and complex export functionality. It's mostly complete but has minor 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 description coverage is 0%, so the description must compensate fully. It adds significant meaning beyond the schema: it explains that 'sphere' filters nodes by category (e.g., 'architecture', 'personal'), 'offset' is for pagination to skip nodes, and 'limit' controls max nodes per call with a default of 500 to avoid context issues. This provides clear semantics for all 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's purpose with specific verb ('export') and resource ('knowledge graph as structured JSON'), distinguishing it from siblings like suma_import (for importing) and suma_clean/forget (for deletion). It explicitly mentions what gets exported: nodes, relationships, and graph metadata.

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 usage scenarios in a bulleted list: migrating data, backing up before a wipe, sharing between machines, and satisfying GDPR requests. It also distinguishes when to use this tool by mentioning it can be paired with suma_import on another instance, clarifying its role versus other tools.

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

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

With no annotations provided, the description carries full burden and discloses key behavioral traits: it's irreversible (⚠️ warning), requires confirmation, has two modes (node_id and keyword), and mentions GDPR compliance implications. It doesn't detail error handling or response format, but covers critical safety aspects.

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 warning, usage guidelines, mode explanations, and parameter details. Every sentence adds value—no fluff. It's front-loaded with the core purpose and critical warning, making it efficient for an agent 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?

Given the tool's complexity (destructive operation with 4 parameters, no annotations, no output schema), the description is complete. It covers purpose, usage, behavioral risks, parameters, and sibling differentiation. No output schema exists, but the description sufficiently guides invocation without needing return value details.

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. It explains all 4 parameters: 'node_id' for exact deletion, 'keyword' for GDPR erasure (case-insensitive), 'scrub_logs' for GDPR compliance, and implies 'ctx' via context in other tools. It adds meaning beyond schema titles, clarifying usage and defaults.

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 delete[s] a node (or all nodes matching a keyword) from the knowledge graph.' It specifies the verb ('delete'), resource ('node'/'knowledge graph'), and distinguishes it from sibling 'suma_clean' for noise removal versus intentional deletion.

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 guidance on when to use it (e.g., wrong facts, GDPR requests, confirmed permanent erasure) and when not to ('DO NOT call this to "tidy up" — use suma_clean'). It names the alternative tool 'suma_clean' and includes prerequisites like running 'suma_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.

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

With no annotations provided, the description carries full burden and does well by explaining the merge parameter's behavior (add vs replace with caution warning). It also implies this is a write/mutation operation through 'import' and 'restore' language. However, it doesn't mention authentication needs, rate limits, or error handling.

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 efficiently structured with a clear purpose statement, bulleted use cases, and organized parameter explanations. Every sentence adds value without redundancy. The 'use with caution' warning is appropriately placed.

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 4-parameter mutation tool with no annotations and no output schema, the description does an excellent job explaining parameters and use cases. However, it doesn't describe the return value or error conditions, leaving some gaps in behavioral understanding despite strong parameter coverage.

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 fully compensates by explaining all 4 parameters: nodes (list of dicts with required fields), edges (optional list with structure), merge (boolean with default and behavior explanation), and even mentions ctx parameter indirectly. It provides crucial format details not in the schema.

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

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

The description clearly states the tool imports nodes and optionally edges into a knowledge graph, specifying the verb 'import' and resource 'knowledge graph'. It distinguishes from siblings like suma_export (exporting) and suma_ingest (likely different ingestion method) by focusing on restoration and migration scenarios.

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 lists three specific use cases: restoring from export output, syncing from Docker to Cloud, and migrating between machines. This provides clear guidance on when to use this tool versus alternatives like suma_export for exporting or suma_ingest for other ingestion methods.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure and excels by detailing critical behavioral traits: the quality gate requiring user confirmation, the prohibition against ingesting raw massive text, the explicit ingestion trigger, node naming conventions, allowed spheres, and relationship verbs. It also implies mutation (adding information) and provides context on auto-classification and relationship extraction defaults.

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 sections (e.g., quality gate, ingest signals, architecture guidelines) and uses bullet points and formatting for readability. While lengthy, every sentence earns its place by providing essential guidance, such as the node naming format and relationship verbs. It could be slightly more concise by integrating some repetitive instructions, but the structure enhances usability.

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 complexity of a knowledge graph ingestion tool with no annotations and no output schema, the description is highly complete. It covers purpose, usage guidelines, behavioral constraints, parameter semantics, and operational details like naming conventions and allowed spheres. The only minor gap is the lack of output information, but this is acceptable as no output schema exists, and the tool's focus is on ingestion rather than return values.

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 adds significant meaning beyond the input schema, which has 0% description coverage. It explains that 'text' should be 'compressed, synthesized information' and not raw data, specifies that 'sphere' defaults to auto-classified 'default' with allowed spheres listed, and clarifies that 'extract_relationships' uses 'universal primitives' like DEPENDS_ON or IMPLEMENTS. However, it does not address the 'ctx' parameter, 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 clearly states the tool's purpose as 'Add new information to the SUMA knowledge graph' with specific guidance on what constitutes meaningful information (e.g., architectural decisions, bugs, business decisions) versus noise (e.g., raw sensor data, intermediate debugging steps). It distinguishes this ingestion tool from sibling tools like suma_search or suma_clean by focusing on adding structured knowledge rather than querying or maintaining the graph.

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 usage guidelines, including a quality gate with clear YES/NO criteria for ingestion, examples of what to ingest and what not to ingest, and an explicit trigger (#memory or #sumamemory) that bypasses the quality gate. It also distinguishes when to use this tool versus alternatives by emphasizing semantic extraction over raw data ingestion and specifying allowed spheres and relationship verbs.

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

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

No annotations are provided, so the description carries the full burden. It discloses return values (content, metadata, emotional weight, centrality, neighbors) and default behaviors for parameters, which is helpful. However, it lacks details on error handling, rate limits, authentication needs, or side effects, leaving gaps for a tool with no annotation coverage.

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 appropriately sized and front-loaded: the first sentence states the purpose, followed by return details and parameter explanations. Every sentence adds value without redundancy, and the structure is clear and efficient.

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, no output schema, and 4 parameters with 0% schema coverage, the description is moderately complete. It covers the core functionality and parameters but lacks error handling, output format specifics, and behavioral context like side effects or limitations, which are important for a tool in this context.

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 compensate. It adds meaning by explaining node_id (e.g., 'SHARATH', 'ACCENTURE') and clarifying the purpose of include_neighbors and include_weight_profile, including their defaults. This goes beyond the schema's basic titles, though it doesn't fully detail all parameters (e.g., 'ctx' is unexplained), preventing a perfect score.

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: 'Get a specific node from the SUMA knowledge graph with its weight profile.' It specifies the verb ('Get'), resource ('node'), and scope ('SUMA knowledge graph'), distinguishing it from siblings like suma_search or suma_edges. However, it doesn't explicitly differentiate from suma_entity (which might retrieve entity information), keeping it from a perfect score.

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 no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like suma_entity or suma_search, nor does it specify prerequisites or contexts for usage. The only implied usage is retrieving a specific node, but no exclusions or comparisons are provided.

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

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

No annotations are provided, so the description carries the full burden. It mentions detecting 'repeated behaviors, temporal patterns, and cross-pattern causation,' which gives some behavioral context, but lacks critical details like whether this is a read-only operation, what permissions are needed, how results are returned (e.g., format, pagination), or any rate limits. For a pattern-finding tool with zero annotation coverage, this is insufficient.

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 appropriately sized and front-loaded: the first sentence states the core purpose, followed by additional details and parameter explanations. It avoids unnecessary fluff, but the formatting with line breaks could be slightly improved for readability, and the parameter section is a bit terse.

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 complexity (pattern detection in a knowledge graph), no annotations, no output schema, and 3 parameters with 0% schema coverage, the description is moderately complete. It covers the purpose and two parameters well but misses the 'ctx' parameter and lacks output details. It's adequate for basic understanding but has clear gaps for effective use.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the 'query' parameter as 'Topic or keyword to find patterns for' and 'include_cross_patterns' as 'Also detect cross-pattern causation. Default True.' This adds meaningful semantics beyond the schema's bare titles. However, it omits the 'ctx' parameter entirely, leaving it undocumented, which prevents a perfect score.

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: 'Find K-WIL algorithm patterns — hidden connections in the knowledge graph.' It specifies the verb ('Find') and resource ('patterns'), and distinguishes it from siblings by focusing on pattern detection rather than cleaning, coverage, entities, etc. However, it doesn't explicitly differentiate from all siblings (e.g., 'suma_search' might also find things), so it's not a perfect 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 description provides no guidance on when to use this tool versus alternatives. It doesn't mention any sibling tools or contexts where this tool is preferred, nor does it specify prerequisites or exclusions. The only implied usage is for finding patterns, but this is too vague for effective selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes critical behavioral traits: the tool validates connection and authentication, failure blocks all other tools, and it returns specific data (server version, org_id, tier, weight_profile, timestamp). However, it doesn't mention potential error responses or rate limits, leaving some behavioral aspects uncovered.

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 appropriately sized and front-loaded with the critical instruction in the first line. While it includes protocol details that are valuable for context, some repetition (e.g., 'A session with no suma_ping is a session flying blind') could be trimmed. Overall, most sentences earn their place by reinforcing usage rules.

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 (simple verification), no annotations, and no output schema, the description provides strong contextual completeness. It explains the tool's critical role, failure implications, return values, and protocol position. The main gap is the undocumented 'ctx' parameter, but for a ping tool, this is a minor omission.

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

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

The input schema has 1 parameter with 0% description coverage, and the description doesn't mention the 'ctx' parameter at all. However, since the tool appears to be a simple ping/verification with no required parameters, the lack of parameter documentation is less critical. The description compensates by explaining what the tool verifies, though it doesn't address the optional parameter's purpose.

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 as verifying MCP connection, org_id, and Bearer token validity with specific verbs ('verifies', 'confirm connection'). It explicitly distinguishes this tool from siblings by emphasizing it must be called first before any other tool, making its role distinct in the 3-step protocol.

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 usage guidelines: 'CALL THIS FIRST, ALWAYS, BEFORE ANY OTHER TOOL' and 'Do NOT skip to suma_search or suma_ingest without calling this first.' It names specific alternatives (suma_search, suma_ingest) to avoid and outlines a clear 3-step protocol with this as step 1, leaving no ambiguity about when to use it.

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

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

With no annotations provided, the description carries full burden and delivers rich behavioral context: it explains the tool's critical role in preventing outdated answers, describes namespace filtering behavior (hardware exclusion by default), memory protection via circuit_breaker, and the impact of similarity_threshold on result precision. It doesn't fully cover output format or error handling.

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 appropriately sized and well-structured with clear sections (purpose, rules, usage examples, parameter explanations), though slightly verbose. Every sentence adds value - no fluff or repetition. It could be slightly more front-loaded by moving parameter details after core usage guidelines.

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 complex 7-parameter search tool with no annotations and no output schema, the description provides excellent context about when/why to use it, parameter behaviors, and domain filtering. The main gap is lack of information about return format or error conditions, which would be helpful given the absence of output schema.

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

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

With 0% schema description coverage for 7 parameters, the description fully compensates by providing clear semantic explanations for all parameters: query (natural language, be specific), similarity_threshold (match quality trade-off), circuit_breaker (memory protection), depth (graph traversal), sphere (domain filter with detailed use cases), and sentiment (filter type). It 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?

The description clearly states the tool's purpose: to search SUMA (a knowledge base) for live project information before answering architecture or project questions. It specifies the verb 'search' and resource 'SUMA', and distinguishes it from siblings by emphasizing its role as the primary search tool (STEP 3 OF 3) among many SUMA-related 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 provides explicit, comprehensive usage guidelines with clear ✅/❌ examples of when to call vs. skip, plus detailed domain filtering instructions (sphere parameter usage). It explicitly states the 'golden rule' for when this tool is mandatory versus when alternatives (like factual recall) are appropriate.

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

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

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: it's a read operation (implied by 'Return'), requires authentication ('reads from the authenticated org'), has no arguments, and describes the return content. However, it lacks details on rate limits, error conditions, or data freshness.

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 appropriately sized and front-loaded: the first sentence states the core purpose, followed by usage context and detailed return values. Every sentence adds value with zero waste, making it efficient for an AI agent 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?

Given the tool's moderate complexity (statistical reporting with no parameters), no annotations, and no output schema, the description is mostly complete. It covers purpose, usage, authentication, and return values. A minor gap is the lack of output structure details (e.g., format of the breakdowns), but the listed metrics provide sufficient context for basic use.

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

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

The input schema has one parameter with 0% description coverage and no documentation. The description compensates by explicitly stating 'No arguments needed — reads from the authenticated org', which clarifies that the parameter is optional or contextual. This adds meaningful semantics 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 the tool's purpose with specific verbs ('Return', 'show') and resources ('graph statistics and shadow telemetry', 'ROI receipt', 'tokens saved', 'graph health metrics'). It distinguishes from siblings by focusing on statistical/telemetry data rather than operations like cleaning, searching, or importing.

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

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

The description provides clear context for when to use this tool ('to show the user their ROI receipt' and for graph health metrics). However, it does not explicitly state when not to use it or name specific alternatives among the sibling tools, though the purpose differentiation implies alternatives exist.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the tool returns a Markdown dump, requires calling suma_topics() first, handles an optional topic parameter with a default to return all nodes (with a size warning), and specifies a default limit. It doesn't mention error handling or performance details, but covers the core operational traits well.

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 core purpose, followed by usage steps and parameter details in a structured format. Every sentence adds value: the first states the purpose, the second provides usage guidelines, and the parameter explanations are clear and necessary. No wasted words.

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

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

Given the tool's complexity (3 parameters, no annotations, no output schema), the description is largely complete. It covers purpose, usage, parameters, and return structure (topic, node_count, markdown). However, it lacks details on error cases, the 'ctx' parameter's role, and exact output format beyond Markdown, leaving minor 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 description coverage is 0%, so the description must compensate. It explains all three parameters: 'topic' (sphere name from suma_topics(), with examples and omission behavior), 'limit' (max nodes per topic with default), and implicitly 'ctx' (though not detailed, its role might be inferred from context). The description adds meaningful semantics beyond the bare schema, though 'ctx' remains vague.

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: 'Return a synthesized Markdown knowledge dump for a specific topic sphere.' It specifies the verb ('return'), resource ('Markdown knowledge dump'), and scope ('specific topic sphere'), and distinguishes it from siblings by mentioning suma_topics() as a prerequisite, unlike other tools like suma_search or suma_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?

The description provides explicit guidance on when and how to use the tool: 'Call suma_topics() first to discover topic names, then call this with one of those topic names.' It also warns about the behavior when the topic is omitted ('may be very large'), offering clear usage context and prerequisites.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the tool performs both retrieval and storage in one call (implying mutation), learns from user interactions, and requires distilled behavioral intent rather than raw data. However, it lacks details on potential side effects, error handling, or performance characteristics, leaving some gaps in transparency.

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

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

The description is well-structured and front-loaded with the core purpose, followed by usage guidelines, exclusions, and parameter details. Every sentence adds value without redundancy, and the information is presented efficiently in a logical flow, making it highly concise 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?

Given the tool's complexity (bidirectional memory with learning) and lack of annotations or output schema, the description does a strong job covering purpose, usage, and parameters. However, it does not detail the return format or potential errors, which could be important for an AI agent. The completeness is high but not exhaustive for such a nuanced 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 description coverage is 0%, so the description must compensate. It adds meaningful semantics for all three parameters: 'message' is explained as 'the distilled behavioral intent of the user (not raw text — synthesize first),' and 'persona' is described with examples ('companion', 'analyst', 'mentor') and a default. The 'ctx' parameter is not mentioned, but the description provides substantial value for the other parameters, justifying a score above baseline.

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 explicitly states the tool's purpose as 'Bidirectional memory — retrieves context AND ingests the refined insight in one call,' which clearly distinguishes it from sibling tools like suma_search by emphasizing both retrieval and storage. It specifies the verb ('retrieves and ingests') and resource ('context and refined insight'), 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?

The description provides explicit guidelines on when to use this tool vs. alternatives, including three scenarios for using suma_talk (ongoing conversation, need for retrieval and storage, personal/reflective content) and two scenarios for using suma_search (only retrieval needed, precise vector search control). It also includes a 'DO NOT' section to avoid misuse, offering comprehensive usage guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the tool's behavior ('Clusters nodes by sphere, counts them, and returns the top topics ranked by node count') and output structure, but lacks details on potential limitations (e.g., rate limits, authentication needs, error conditions). The description is informative but not comprehensive for a tool with no annotation support.

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 efficiently structured in three sentences: the core purpose, the algorithmic behavior, and the usage guideline with sibling reference. Every sentence adds value without redundancy, and key information is front-loaded. It's appropriately sized for the tool's complexity.

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 moderate complexity (clustering and ranking), no annotations, and no output schema, the description does well by explaining the purpose, behavior, and output format in detail. However, it lacks information about the 'ctx' parameter's role and any operational constraints. The description is largely complete but has minor gaps in parameter semantics.

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 1 parameter with 0% description coverage, and the tool description provides no information about the 'ctx' parameter. However, since there are 0 required parameters and the schema includes a default value (null), the agent can invoke the tool without parameter knowledge. The description compensates by fully explaining the tool's purpose and output, making parameter details less critical for basic usage.

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 with specific verbs ('Return a lightweight Table of Contents', 'Clusters nodes by sphere, counts them, and returns the top topics ranked by node count') and distinguishes it from sibling tools by explicitly mentioning its relationship to 'suma_summary' for discovery before drilling in. It identifies the resource ('user's knowledge graph') and the specific output format.

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 guidance on when to use this tool ('Use this before suma_summary to discover which topics exist — then drill into one'), including a clear alternative (suma_summary) and the workflow context. It effectively differentiates this tool from its many siblings by outlining its role in the discovery phase.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes what the tool does (injects context), its token usage (≈120 tokens), and the integration mechanism (QMS webhook to K-WIL graph). However, it doesn't explicitly mention whether this is a read-only or mutating operation, though 'injects' implies it might modify context. No contradictions with annotations 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 clear sections (purpose, usage instructions, integration details, args, returns) and front-loaded key information. It's appropriately sized but could be slightly more concise by integrating the QMS integration note into the main flow rather than as a separate paragraph.

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 and no output schema, the description does a good job explaining the tool's purpose, usage, parameters, and return values (assigned_tickets, recent_context, greeting_context). However, it doesn't fully cover all parameters (missing 'ctx') and lacks explicit behavioral details like error handling or rate limits, which would be helpful for a context-injection 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 description coverage is 0%, so the description must compensate. It explains the semantics of user_name ('Developer's name... Used to find assigned tickets') and user_email ('Used as fallback identity if name not provided'), adding clear meaning beyond the schema. However, it doesn't mention the 'ctx' parameter at all, leaving one of three 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?

The description clearly states the tool's purpose: 'Injects zero-shot context for this developer — their assigned tickets, recent high-priority work, open architectural decisions, and active blockers.' It specifies the exact resources (tickets, work, decisions, blockers) and distinguishes from siblings by mentioning it's 'STEP 2 OF 3 — CALL THIS IMMEDIATELY AFTER suma_ping, BEFORE SPEAKING.'

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 usage guidelines: 'CALL THIS IMMEDIATELY AFTER suma_ping, BEFORE SPEAKING' and 'DO NOT skip this step to "save tokens."' It also explains the alternative (not using it wastes developer time) and includes integration context with QMS, making it clear when and why to use this tool.

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