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

The description explicitly states that deletion is permanent, a critical behavioral consequence for a destructive operation. It also warns about the risk of a full-agent wipe if no filter is provided, which is transparent about the tool's potential impact. No annotations are present, so the description carries the full burden, and it meets that need.

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, using only two sentences to convey the purpose, safety requirement, and alternative action. It avoids redundancy and is well-structured, with the main action first followed by critical cautions.

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 provides enough context to understand the basic operation and safety constraints, but it does not explain the return value, error handling, or how multiple filters are combined (AND vs OR). Since there is no output schema, these gaps leave some ambiguity for the agent.

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 summarizes the filter types (tags, importance range, time window, or memory type) that map to most parameters, adding context beyond the schema. However, agent_id and session_id are not mentioned in the description, and the schema descriptions are uneven (memory_type lacks a description). Thus, parameter coverage is partial.

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: bulk-deleting memories that match specified filters. It distinguishes itself from singular deletion tools by using the explicit term 'Bulk-delete' and enumerating the filter dimensions (tags, importance range, time window, or memory type).

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 important usage guidance, including the requirement that at least one filter must be provided to prevent accidental full wipe, and advises using an alternative for lowering importance instead of deletion. It does not explicitly compare with dakera_forget, but the safety and alternative guidance is useful.

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?

Since no annotations are provided, the description carries the burden. It implies a read-only listing operation without side effects. It does not mention any destructive actions, but also does not explicitly state read-only or discuss rate limits or auth, so slightly below perfect.

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 very concise, using three short sentences. It front-loads the core function and includes key usage constraints without any fluff. Each 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?

Provides essential context such as the purpose, the alternative tool, and the filter requirement. However, it lacks details about the return format (no output schema) and does not describe all parameters explicitly, so it is not fully complete.

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

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

Schema description coverage is 63% (5 of 8 parameters have descriptions). Tags, importance range, and time window are described, but agent_id, session_id, and memory_type lack descriptions. The description mentions filtering by type or session, but does not explicitly map these to the parameters, so agents must infer their meaning.

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 performs 'filter-based memory listing' with a specific verb and resource. Also differentiates from dakera_recall by explicitly noting the preference when semantic search is not needed.

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

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

Provides an explicit condition for choosing this tool over dakera_recall ('when semantic search is not needed') and states the requirement that at least one filter must be provided. This gives clear 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?

The description discloses that the tool returns only names and summaries without loading full schemas, giving insight into its behavior and efficiency. However, it does not explicitly state that it has no side effects (e.g., read-only operation), which is left to inference. Since no annotations are provided, a bit more explicit safety disclosure would be ideal, but the current description is still reasonably transparent.

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

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

The description is two sentences long, concise, and front-loads the primary purpose. It contains no filler words and each sentence adds value: the first states the function, the second provides usage guidance and efficiency rationale.

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 provides sufficient context for an agent to decide when to use this tool: it is a discovery step that avoids loading full schemas. It also names the companion tool for schemas, making the workflow clear. The mention of output (names and summaries) covers the basic expectations even without an 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?

Both parameters (tier and query) are mentioned in the description: 'by keyword or tier.' The description explains that tier is a filter with enum values (core, power, admin, meta, all) and query is a keyword for searching names/descriptions. This provides full semantic coverage without redundancy with 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 that the tool searches the Dakera tool catalog by keyword or tier, which is a specific verb and resource. It also distinguishes this tool from others like dakera_load_tools by emphasizing it returns only names and summaries, making its purpose 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?

Explicit guidance is provided: 'Call this first to find relevant tools, then use dakera_load_tools to fetch only the schemas you need.' This tells the agent exactly when to use this tool versus alternatives and highlights the efficiency benefit of avoiding full schema loads.

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, the description carries full responsibility for behavioral disclosure. It explicitly states that api_key is 'Never persisted — used for this request only', and explains the resolution hierarchy (per-request override → namespace default → server default → GLiNER local). It also notes that entity_types are used only when provider is gliner. These details surface important behavioral traits.

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

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

The description is a single, well-structured sentence. It uses a colon to list the extracted information types and an arrow notation to concisely convey the resolution order. The list of supported providers is compact and informative. No redundant verbiage.

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 the tool (nested override object, provider hierarchy, multiple providers), the description covers the essential operational details. It explains the provider resolution order, the role of namespace, and the persistence behavior of api_key. While it doesn't describe the output format or error scenarios, these are not explicitly required by any output schema or annotation.

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

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

Schema description coverage is 100% with each parameter described. The description adds meaningful context beyond the schema: it explains the provider override hierarchy, the namespace default behavior, and the conditional use of entity_types. The extractor_override nested object is also well-documented with its own 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: 'Extract structured information (entities, topics, key phrases, summary) from arbitrary text'. The verb 'extract' and the specific resource (text) make the action unambiguous. It distinguishes itself from sibling tools by focusing on extraction rather than search, store, or recall operations.

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 detailed guidance on when and how to use the tool, explaining the provider resolution hierarchy and listing supported providers. It clarifies that entity_types are only used with GLiNER and that api_key is request-scoped. While it doesn't explicitly contrast with alternatives, the provider hierarchy and parameter conditions give clear usage context.

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?

The description discloses that deletion is immediate and irreversible, and that using tags results in bulk deletion. With no annotations, this covers key behavioral aspects, though it does not mention potential side effects like cascading deletions or missing confirmation.

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, front-loaded with the purpose, and well-structured. It covers purpose, usage, and an alternative in two sentences without unnecessary detail.

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 lack of an output schema, the description does not need to explain return values. It covers the essential 'when' and 'how' but leaves gaps regarding agent_id semantics and the interaction between parameters, which could affect an agent's correct usage.

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 provides descriptions for memory_ids and tags, but agent_id has no description in either the schema or the tool description. The description explains the usage of memory_ids and tags, but does not clarify the role of agent_id or whether the two parameters can be combined or are mutually exclusive.

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 permanently delete memories by ID or tag. It specifies the resource (memories) and the method (by ID or tag), and distinguishes it from sibling tools like dakera_batch_forget and dakera_memory_importance.

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: 'Provide memory_ids for exact removal or tags to bulk-delete all memories sharing those tags.' It also names an alternative (dakera_memory_importance) for a different use case (suppression instead of deletion), making the decision clear.

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, the description must convey behavioral traits. 'Search' implies a read-only operation with no side effects, and the description does not hint at any modifications. However, it does not explicitly state that no data is altered, so a minor gap exists.

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

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

The description is compact, using two sentences to convey purpose and usage guidance without unnecessary verbiage. It is well-structured and front-loads the core function.

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

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

No output schema exists, so the description need not explain return values. It fully covers the tool's purpose, selection criteria, and relationship to sibling tools, leaving no critical information missing for an agent to use it correctly.

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

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

All four parameters (query, top_k, filter, namespace) have descriptions in the schema, giving high coverage. The tool description adds no extra parameter-specific insights, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool performs 'BM25 keyword search over indexed documents' and explicitly distinguishes it from vector and hybrid search alternatives. It identifies the specific resource (indexed documents) and the verb (search) without ambiguity.

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

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

The description provides direct usage guidance: 'Use over vector search when exact-term recall matters' and 'For semantic+keyword combined use dakera_hybrid_search.' This tells the agent exactly when to select this tool over its 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, the description explains the hybrid algorithm and weight behavior, but does not disclose safety, permissions, cost, or error behavior. The 'single pass' note gives a performance hint, but overall transparency is limited.

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

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

Two concise, front-loaded sentences with no redundancy. Every sentence provides essential information, and the structure is clear.

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 8 parameters, nested filter object, and no output schema, the description is somewhat minimal. It does not explain return values, pagination, or results handling, leaving gaps for a complex search 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 75% (two parameters lack descriptions in schema). The description adds meaning by explaining the vector parameter for BM25-only mode and the vector_weight range, enhancing understanding 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 clearly specifies a hybrid search combining BM25 and vector ANN in a single pass, and distinguishes from siblings by noting BM25-only mode and use case for RAG when pure methods are insufficient.

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 use ('RAG when pure semantic or keyword search alone is insufficient') and how to configure modes (omit vector for BM25-only, adjust vector_weight). Lacks explicit exclusion criteria but provides clear context.

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 to rely on, the description carries the full burden of disclosing behavioral traits. However, it only states the action ('build a knowledge graph') without clarifying whether this is a read-only operation, what side effects exist, or what the return structure looks like. The term 'build' could imply a mutation, but this is left ambiguous.

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

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

The description is two sentences long, with no redundant content. It front-loads the primary function, then adds the use case and the differentiation from the sibling tool. Every word contributes to clarity.

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 is provided, so the description should hint at what the tool returns. It does not mention the result format (e.g., nodes, edges, graph object) nor any error or edge-case behavior. Given the complexity of building a knowledge graph, the description is insufficient for an agent to fully anticipate the tool's output.

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 covers 75% of parameters with descriptions, but the tool description adds no additional insight about any of them. The missing description for agent_id is not compensated for by the prose. The description does not clarify acceptable values, defaults, or interactions between parameters, leaving the semantics solely to 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 function (build a knowledge graph using embedding similarity), its intended use case (explore concept connections), and explicitly differentiates it from a sibling tool (dakera_graph_traverse) for BFS traversal of existing graphs.

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 provides explicit guidance on when to use this tool ('Use to explore how a concept connects to stored knowledge') and when to use an alternative ('For BFS traversal of an existing linked graph use dakera_graph_traverse'). No ambiguity remains.

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?

The description discloses the output behavior in detail: it returns schemas for found tools and a not_found list for unrecognized names. This transparency about both success and failure cases exceeds typical descriptions and is fully transparent for a read-only 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?

The description is concise, consisting of two sentences that directly state the function, usage timing, and output behavior. Every word serves a purpose, with no extraneous information or redundancy.

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

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

For a simple tool that fetches schemas, the description provides all necessary context: what it does, when to use it (after discover_tools), and what it returns (schemas plus not_found list). No additional information is needed for an agent to invoke it correctly.

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

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

The only parameter 'tools' is described as 'Tool names to load schemas for', which clearly explains its purpose and format. The schema description is comprehensive, and the tool description adds no ambiguity. Coverage is 100%.

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

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

The description clearly states the tool fetches the full inputSchema for one or more named tools, using specific verb 'Fetch' and resource 'tools'. It also distinguishes itself from siblings by specifying 'Use after dakera_discover_tools' and describing the return behavior.

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 instructs when to use the tool ('Use after dakera_discover_tools'), providing clear timing guidance. It also implies it is the appropriate tool for loading schemas, while other tools like search or extract serve different purposes.

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 exist, so the description carries the burden. 'Retrieve' implies a read-only operation, and the description adds detail about KG expansion behavior, but does not explicitly state side-effect-free or auth requirements. However, the read-only intent is clear from the verb.

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

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

Two sentences, front-loaded with purpose, and every phrase provides useful information (top-k, semantic closeness, preference, include_associated). No 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?

Given 7 parameters and no output schema, the description provides the key usage context (preference over batch recall, KG expansion). However, the required agent_id parameter has no schema description and is not mentioned in prose, leaving a small gap in 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 meaning to 'top_k' with 'top-k' and to 'include_associated' with the KG edge explanation. Since the schema already provides descriptions for most parameters, this adds context beyond the schema, though some parameters (e.g., agent_id) are not elaborated.

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

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

Clearly states the action (retrieve), the resource (memories), and the criterion (semantically closest to a query). It also distinguishes from the sibling dakera_batch_recall, making the purpose 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?

Explicitly says to prefer this over dakera_batch_recall for query-based retrieval, and advises setting include_associated to expand via KG edges. This gives clear when-to-use and alternative 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 for behavioral traits. It does not explicitly state whether the operation is read-only or has side effects, nor does it mention permissions or rate limits. The description is honest but lacks explicit transparency about its non-destructive nature.

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

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

The description is a single, concise sentence that packs the core function and the key usage guidance. Every word is necessary, and it is well-structured for quick reading.

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 search tool with two optional filters, the description is sufficient for an agent to decide when to invoke it. It does not specify the return format, but since no output schema is defined and the tool is inherently a search, the missing information is not critical. The description could be slightly richer by mentioning the nature of results, but it is overall complete enough.

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 already has descriptions for 4 of 5 parameters (80% coverage), which is high, so a baseline of 3 is appropriate. The description text merely echoes the 'tag' and 'memory type' filters without adding further meaning, and it does not clarify the purpose of agent_id beyond being required.

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 performs semantic search with optional filters for tags and memory type. It also contrasts with the sibling tool dakera_recall, providing a specific use case, making the purpose 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 explicitly says 'Prefer over dakera_recall when results must be constrained by tag or type alongside the semantic match,' giving direct guidance on when to use this tool versus the alternative. This tells the agent exactly the conditions favoring this tool.

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 the consequence of not calling (orphaned sessions) and mentions that the summary is retrievable via another tool, adding behavioral context. However, it does not describe side effects like idempotency, error handling, or what happens if the session is already closed.

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

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

The description is two sentences, front-loaded with the purpose, followed by usage guidance and a cross-reference. No unnecessary words; every sentence earns its place.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, timing, and a related tool reference. It lacks a mention of return value or error scenarios, but these are not critical for such a straightforward operation.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description adds only marginal value: it notes that the summary is optional and that it can be retrieved later via dakera_session_get. This does not significantly enhance the schema's documentation.

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

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

The description clearly states the action ('Close') and the resource ('active session'), and mentions the optional summary. It is distinct from sibling tools like dakera_session_start, making its purpose 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?

Explicitly states when to call the tool ('Always call at run end (even on error)') and the reason (to avoid orphaned sessions). It does not name alternatives or exclusions, but the directive is strong enough for an agent to know 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?

The description implies state creation (opening a session) and organizes memories, which is a side effect, but it does not detail permissions, authentication, or potential side effects on existing data. Since no annotations are provided, the description carries the full burden but only partially discloses behavior.

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

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

The description is concise, consisting of two sentences that directly convey the core purpose and the metadata usage. There is no redundant or irrelevant 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 description covers the main behavior, return value, and the role of metadata, but it omits an explanation of agent_id and lacks details on error handling or session lifecycle. Given the tool's simplicity and lack of an output schema, the description is reasonably complete but has 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?

The schema covers two parameters, with metadata having a description in the schema and the prose. However, agent_id is required but has no description in the schema or the description text, leaving its purpose unexplained. With schema coverage at 50%, the description does not compensate for the missing agent_id semantics.

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 function: it opens a new session, returns a session_id, and groups stored memories under a shared context. It uses a specific verb ('open') and resource ('session'), distinguishing it from the other sibling tools like search or store.

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 gives context about attaching metadata for later retrieval, but does not explicitly state when to use this tool versus alternatives. It does not mention any specific conditions or exceptions, so usage guidance is implicit rather than explicit.

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

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

With no annotations provided, the description carries the full burden. It mentions the importance default and decay behavior, and notes that tags are optional. It does not specify return values or error handling, but the core write semantics and importance decay are transparent enough.

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

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

The description is two sentences, concise and front-loaded with the primary action. It avoids unnecessary detail and keeps the most relevant usage guidance immediately visible.

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 provides enough context for an agent to decide when to use the tool, especially with the importance/decay explanation. It does not elaborate on every parameter, but the schema already covers those details, so the description fills the key contextual 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 high (86%), and the description adds meaning beyond the schema by explaining the importance default (0.5) and the threshold for critical memories (0.8–1.0) that survive decay. It also clarifies that tags are optional, augmenting the parameter details.

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 the verb 'persist' and the resource 'memory for an agent', and it distinguishes itself from sibling tools like dakera_search and dakera_forget by focusing on the write operation.

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 says 'Use to save facts, decisions, or context for future retrieval', providing clear guidance on when to use. It does not explicitly state when not to use, but the sibling tool names make the contrast obvious, so the guidance is adequate.

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