Penfield Memory

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

Complements readOnlyHint=true by clarifying the operation loads configuration without mutation. Adds valuable context about what the briefing contains (persona, voice, quirks) beyond what annotations indicate. Could mention idempotency or caching behavior, but adequately covers the scope.

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?

Front-loaded with critical instruction (call first), followed by purpose, output specification, and rationale. Visual emphasis (⚡) and bullet lists enhance scannability. Example demonstrates async invocation pattern. No wasted text despite length.

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 returns structured data (output schema exists), the description appropriately previews the briefing content without duplicating the full schema. Covers initialization logic, return value preview, and sequencing prerequisites completely for a zero-parameter initialization 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?

Zero parameters per schema (baseline 4). Description appropriately omits parameter discussion since the tool requires no inputs. Schema coverage is 100% (empty object confirms no params needed), so no compensation 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?

Excellent specificity with clear verb ('Loads') and resource ('personality configuration and user preferences'). Distinguishes from siblings (e.g., 'recall', 'retrieve_artifact') by focusing on session initialization and identity establishment rather than data retrieval or storage.

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 sequencing constraints with 'CALL THIS TOOL FIRST IN EVERY NEW CONVERSATION' and 'before doing anything else'. Clear rationale provided ('ensures you have context'). Establishes temporal precedence over all sibling tools without ambiguity.

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?

Annotations indicate readOnlyHint=false (mutation) and openWorldHint=true. Description adds semantic transparency by explaining that connections create 'knowledge graphs,' the meaning of relationship semantics (e.g., 'supersedes' vs 'updates'), and consequences ('smarter recall'). Could clarify idempotency behavior for duplicate connections.

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

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

Well-structured with hierarchical headers and front-loaded purpose. Length is substantial due to necessary enumeration of 20+ relationship types (required given open string parameter), but every section earns its place for agent reasoning. Minor deduction for 'Returns' section which duplicates output schema.

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

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

Given 0% schema coverage and complex graph semantics domain, description is comprehensive. Includes parameter docs, relationship taxonomy, usage workflow, and concrete examples—sufficient for correct invocation without external reference.

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

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

Schema coverage is 0% (only titles). Description fully compensates with an Args section documenting all 4 parameters: UUID semantics for memories, enumerated relationship_types (critical since schema lacks enum), strength range (0.0-1.0), and ctx annotation.

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?

Opens with precise action ('Connect memories') and outcome ('build knowledge graphs'). Immediately distinguishes from sibling 'store' by stating 'After using store...' and implies distinction from 'disconnect' by focusing on creation semantics.

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

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

Provides explicit temporal guidance ('immediately connect related memories'), a 5-question workflow for decision-making, and contextualizes when specific relationship types apply. Clear activation pattern post-storage.

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?

Annotations already declare destructiveHint=true, so the description's emphasis on 'permanently removes' is consistent but redundant. It adds valuable context that the operation also deletes an 'associated memory record,' which is not indicated in annotations. It does not address idempotency, error cases (e.g., missing path), or authorization requirements.

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

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

The description is appropriately sized with a clear structure: one-line summary, behavioral details, Args section, and Returns section. Every sentence adds value. The Returns section is slightly vague ('Dict with success status') but acceptable given the output schema exists.

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 single-parameter destructive operation, the description covers the essential mechanics and permanence warning. However, given the destructive nature and lack of schema descriptions, it should mention error behavior (e.g., what happens if path doesn't exist) or whether the operation is idempotent. The output schema exists, so detailed return value explanation is not required in the description.

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 compensates effectively by documenting the 'path' parameter as 'Full path of the artifact to delete.' It also clarifies that 'ctx' is automatically provided, which helps the agent understand it should not manually supply this argument.

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 deletes artifacts from storage and permanently removes associated memory records. It uses specific verbs (delete, removes) and identifies the resource (artifact, memory record). However, it does not explicitly distinguish this from sibling tools like 'retrieve_artifact' or 'save_artifact'.

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 emphasizes 'permanently removes,' implying irreversibility and warning against accidental use. However, it lacks explicit guidance on when to use this versus alternatives (e.g., 'use retrieve_artifact first to verify contents') or prerequisites like necessary permissions.

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?

Annotations declare destructiveHint=true. The description adds critical clarification that only the relationship is deleted ('Deletes the relationship between two memories'), implying the memory nodes persist. It also establishes domain context ('knowledge graph'). No contradictions with annotations.

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 docstring structure is clear but verbose. The Returns section is redundant given the output schema exists, and the Examples block, while helpful, contributes to length. The core semantic content is front-loaded in the first two sentences.

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 2-parameter destructive operation with existing annotations and output schema, the description provides adequate coverage including parameter semantics, behavioral context, and invocation examples. It appropriately compensates for the schema's lack of property descriptions.

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 Args section compensates effectively by documenting both 'from_memory' as 'Source memory UUID' and 'to_memory' as 'Target memory UUID', adding semantic directionality and format expectations (UUID) absent from the raw 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 uses specific verbs ('Remove', 'Deletes') with clear resource ('connection between memories', 'relationship'). It effectively distinguishes from sibling 'connect' (creates connections) and 'delete_artifact' (removes nodes/artifacts, not 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 implies appropriate use by specifying it removes relationships rather than memories themselves, implicitly distinguishing from memory deletion tools. However, it lacks explicit guidance on when to prefer this over other modification tools or prerequisites for the operation.

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?

Annotations declare readOnlyHint=true and openWorldHint=true. Description adds valuable behavioral constraints not in schema: max_depth ceiling of 10, specific return structure (paths_found, max_depth_reached), and automatic nature of 'ctx' parameter. Does not disclose performance implications of deep traversal.

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?

Uses docstring format (Args/Returns/Examples) which is structured but slightly verbose for agent consumption. Every section adds value given 0% schema coverage, though headers like 'Args:' consume tokens without adding semantic content. Front-loaded with clear one-line summary.

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?

Comprehensive for a graph traversal tool: covers all parameters (compensating for empty schema), documents return values despite presence of output schema, provides runnable example, and explains traversal depth mechanics. Minor gap on explaining 'path' structure 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%, requiring description to carry full burden. Successfully documents all 3 schema parameters: clarifies start_memory expects UUID, explains max_depth traversal semantics and constraints, and describes relationship_types as optional filters. Deducted point for not enumerating valid relationship type values.

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?

Clear verb-resource combination (traverses knowledge graph / explores connections) and specific functionality (graph traversal by depth). Lacks explicit differentiation from sibling tools like 'search' or 'recall' which also retrieve memories.

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 concrete examples showing invocation patterns, which offers implied usage guidance. However, lacks explicit when-to-use guidance versus alternatives like 'search' or 'fetch', and no prerequisites are mentioned.

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?

Annotations already declare readOnlyHint=true. Description adds that it returns a single memory with citation support (id, title, url, text fields), and explains the tool's purpose beyond annotations.

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

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

Well-structured with clear sections: purpose, rationale, args, returns. Slightly lengthy but every sentence is informative. Could be more 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?

For a simple read-only tool with one parameter and an output schema, the description covers purpose, usage context, return fields, and rationale. Complete and sufficient.

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?

Only one parameter (id) with 0% schema description coverage. Description adds 'Memory UUID to fetch', which clarifies the expected input beyond the raw schema type. Good but minimal additional context.

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 a memory by ID, distinguishes it from native alternatives like recall, and specifies its role for ChatGPT Connector compatibility.

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 (ChatGPT Deep Research requirement) and when not to (native MCP clients should use recall or API endpoint). Provides clear alternatives.

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?

Annotations declare readOnlyHint and openWorldHint. The description adds behavioral context: non-recursive listing and separation of folders/files. No contradiction with annotations.

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, well-structured with a summary, parameter docs, return type, and examples. Every sentence adds value without redundancy.

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

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

The description includes a clear return format and examples, compensating for the output schema not being provided. It covers the tool's functionality sufficiently for a list 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?

With 0% schema description coverage, the description compensates by explaining both parameters: path_prefix as default '/' and name_pattern as optional case-insensitive filter. This adds meaning beyond the schema's type and default.

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

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

The description clearly states the tool lists artifacts in a directory and returns immediate contents non-recursively, separating folders and files. This specific verb and resource distinction differentiates it from sibling tools like explore or search.

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

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

While the description implies usage for listing directory contents and shows examples, it does not explicitly state when to use this tool over siblings like explore or search. The purpose is clear but lacks explicit when-not-to-use 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?

Annotations declare readOnlyHint=true and openWorldHint=true, which the description supports by using read-only verbs ('List', 'Shows'). The description adds valuable behavioral context: pagination support (limit/offset), filtering capabilities (name_pattern), output verbosity control (include_descriptions), and the checkpoint concept for multi-agent workflows—none of which are in annotations.

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

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

The description follows a structured docstring format (summary, Args, Returns, Examples) appropriate for compensating poor schema coverage. While lengthy due to manual parameter documentation and examples, every section earns its place. The key information is front-loaded in the first sentence.

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 4 parameters with 0% schema coverage, the description adequately documents inputs. The Returns section is somewhat vague ('Dict with list...'), though the Examples section compensates by showing actual return structure. The presence of output schema means the description doesn't need exhaustive return documentation, but parameter coverage is 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?

With 0% schema description coverage, the description carries the full burden of parameter documentation. It excellently compensates by providing detailed semantics for all 4 parameters: limit (with default 20 and max 100), offset (pagination), name_pattern (case-insensitive substring matching), and include_descriptions (compact vs full output). Note: description mentions a 'ctx' parameter not present in schema, but documents the actual 4 parameters comprehensively.

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

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

The description opens with a specific verb and resource ('List available context checkpoints') and clarifies these are 'saved contexts available for multi-agent workflows.' It effectively distinguishes from siblings like save_context (creation) and restore_context (mutation) by focusing on read-only listing, though it doesn't explicitly contrast with list_artifacts.

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 usage examples showing filtering and pagination patterns, but lacks explicit guidance on when to use this tool versus alternatives like list_artifacts or save_context. No 'when-not-to-use' or prerequisite conditions are specified despite having multiple sibling context/artifact management 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?

Beyond the readOnlyHint annotation, the description adds valuable behavioral context: it explains the hybrid search methodology, documents that inactive memories are excluded by default, clarifies the OR logic for tags, and discloses that document results include surrounding context chunks (2 before/after).

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

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

Well-structured with clear sections (intro, Args, Returns, Examples, Notes). Front-loaded with purpose. The 4 examples are slightly lengthy but provide concrete value given the filtering complexity. Every section conveys necessary information without redundancy.

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

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

Given 7 parameters with no schema descriptions and the presence of an output schema, the description is remarkably complete: it documents all inputs, summarizes return values, provides multiple usage examples, and explains edge cases (inactive memory handling, document chunk 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 (only titles provided), the Args section fully compensates by documenting all 7 parameters with clear semantics, formats (ISO 8601 for dates), defaults (e.g., limit default 10), and logic (OR for tags).

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 uses 'hybrid search to find relevant memories, documents, and connections' (specific verb+resources), but does not explicitly distinguish when to use 'recall' versus the sibling 'search' tool.

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

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

No explicit 'when to use' guidance is provided, but the extensive examples section demonstrates implied usage patterns for various filtering scenarios (by date, tags, source type), which helps users understand applicable contexts.

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 goes beyond annotations by disclosing experimental status and a missing feature ('Importance weighting in results not yet implemented'). It also explains the default exclusion of document chunks. The annotations already indicate read-only and open-world behavior, but the description adds valuable context about limitations.

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

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

The description is well-structured with sections for overview, experimental warning, args, returns, and examples. While it is relatively long, every sentence adds value. It could be slightly more concise by removing the redundant 'Args:' label, but overall it is 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 output schema exists, the description adequately describes the return value as a dict with 'top memories, active topics, patterns, insights, and any saved contexts'. It covers all parameters with examples, and the experimental note adds necessary caveats. It is complete for a tool of this complexity.

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

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

Despite 0% schema description coverage, the description thoroughly explains all four parameters: time_window (with valid values), include_documents (boolean, default false), and start_date/end_date (ISO 8601 format with examples). It also shows usage in examples, fully compensating for the missing schema descriptions.

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: 'Reflect on recent thoughts and patterns' and 'Analyzes recent activity to identify patterns, topics, and insights.' It specifies the resource (user memories and optionally document chunks) and the action (analysis), distinguishing it from sibling tools like 'recall' or 'search' which focus on retrieval.

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

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

The description provides explicit usage context: 'Useful for understanding what have I been thinking about?' It explains default behavior and how to include documents with the 'include_documents' parameter. While it doesn't explicitly state when not to use the tool or list alternatives, the context and examples give clear 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?

Exceptional transparency beyond annotations. The extensive JSON example showing the '[API Timeout Investigation...]' output format precisely demonstrates what the agent receives. Explains the cognitive model (reconstructs understanding, not just facts). Clarifies the 'awakening' special case behavior (personality config vs investigation context). Adds significant value beyond the readOnlyHint annotation.

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?

Lengthy but justified given complexity. Structure is logical: purpose → value proposition → concrete output example → cognitive explanation → special case → Args/Returns. The large example is necessary to demonstrate the narrative output format. Could be tightened slightly but every section 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?

Complete for a complex cognitive tool. Covers the narrative reconstruction concept, special awakening case, parameter semantics, and return structure. Given has_output_schema=true, the description appropriately focuses on explaining the cognitive model rather than return value mechanics, while still providing the example 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?

Fully compensates for 0% schema coverage. Documents 'name' parameter extensively: accepts exact match (case-sensitive), UUID from list_contexts, or special value 'awakening'. Documents 'limit' as memory count cap. References sibling tool list_contexts for UUID discovery, aiding tool chaining decisions.

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?

Excellent clarity with 'Resume work from a saved cognitive context' - specific verb (resume) + resource (cognitive context). Explicitly distinguishes from siblings like 'awaken' via the 'SPECIAL CASE: restore_context(awakening)' section, and differentiates from simple memory recall by emphasizing narrative reconstruction vs data retrieval.

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

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

Clear context via the detailed investigation example showing when to use (resuming complex multi-step work). Implies distinction from 'recall' (which returns raw memories) by emphasizing narrative briefing, but lacks explicit 'when not to use' or direct comparison. The awakening special case provides concrete alternative routing.

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?

Annotations declare readOnlyHint=true (safe read). Description adds context that artifacts are stored and retrieved by path, mentions 'error message' for failure modes. Does not address openWorldHint implications or whether paths areabsolute/relative.

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?

Docstring structure is readable but verbose. The 'Returns' section is redundant given output schema exists. Examples are helpful for a retrieval tool, though the Returns section could be omitted.

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?

Adequate for a single-parameter retrieval tool. Description covers the undocumented parameter via Args section. Output schema handles return values, though 'error message' mention hints at error 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?

Excellent compensation for 0% schema coverage: describes the path parameter as 'Full path' with concrete example '/project/docs/api.md'. Agents can understand the expected format despite empty schema 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?

Clear verb ('Retrieve'/'Fetches') and resource ('artifact') with scope ('from storage'). The phrase 'previously saved' helps distinguish from save_artifact, though it could clarify distinction from siblings like fetch/recall.

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

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

The phrase 'previously saved artifact' implies usage constraints (only for existing saved artifacts), providing implied guidance. However, lacks explicit when-to-use versus alternatives like fetch or recall.

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?

Annotations declare readOnlyHint=false and openWorldHint=true; the description adds valuable behavioral context beyond these hints, specifically noting that content is 'indexed for search' and stored in an 'organized file structure'. It also documents return patterns (success messages vs errors) not covered by annotations.

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?

Follows a clear docstring structure (summary, Args, Returns, Examples) with the purpose front-loaded in the first sentence. The examples are somewhat verbose (Python REPL style) but serve as practical documentation. No wasted sentences in the descriptive sections.

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 2-parameter tool with no nested complexity, the description is complete. It compensates for missing schema descriptions via Args documentation, includes return value documentation (addressing the output schema presence), and provides concrete usage examples showing expected return formats.

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 Args section compensates effectively by documenting both parameters ('File content to save', 'Full path including filename') with a concrete path example. Examples further illustrate usage patterns, though detailed format constraints for content types could be clearer.

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 'Save an artifact to storage' with specific resource types (diagrams, notes, code) and mentions indexing behavior. It distinguishes from retrieve_artifact and delete_artifacts siblings implicitly through the verb 'save', but does not differentiate from similar storage siblings like 'store' or 'save_context'.

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

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

While the description characterizes suitable content types (user-created diagrams, notes, code), it provides no explicit guidance on when to choose this tool over similar storage siblings like 'store', 'save_context', or 'update_memory', or prerequisites for 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?

Discloses beyond annotations: explains hybrid search on description, memory attachment behavior, reference resolution reporting, and return values. Annotations already indicate write operation and open world, but description adds significant behavioral context.

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

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

Well-structured with clear sections (purpose, reference syntax, returns). Some redundancy (e.g., repeated mention of hybrid search) but overall 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?

Comprehensive for a complex handoff tool: covers purpose, reference resolution, error reporting, and points to external resources. Output schema exists, but description still adds value.

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?

Despite 0% schema coverage, the description contains a detailed Args section explaining both parameters, including valid usage of memory references and default values. Fully compensates for missing schema descriptions.

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

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

The description clearly states it saves a cognitive checkpoint for handoff, with a specific verb ('save'), resource ('context'), and purpose. It distinguishes from siblings like 'restore_context'.

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

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

Explicitly states when to use (handoff to another agent or future self) and provides guidelines for memory references (UUIDs vs phrases). Mentions a separate prompt for full hygiene guide, but lacks explicit when-not-to-use 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?

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds that the tool returns results with citation support (id, title, url, text) and shares identical hybrid-search semantics with recall. No contradictions, and it adds value beyond annotations by detailing return fields.

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 purpose, then explains context, then return format, then parameters. While not overly long, it includes necessary explanations. Could be slightly more concise, but the structure is logical.

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 simplicity and presence of output schema and annotations, the description covers purpose, usage guidance, return fields, and parameters. It lacks details on pagination or default behavior when limit is exceeded, but overall provides sufficient context for an AI 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?

Schema description coverage is 0%, so the description should add meaning. However, it mostly restates schema defaults and titles for `query` and `limit`. For `include_inactive`, it adds 'superseded/contradicted memories', which is helpful. The description also lists a `ctx` parameter not present in the schema, causing confusion. Overall minimal added value.

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 searches for memories. It distinguishes from sibling `recall` by noting `recall` is preferred for native MCP clients, and explains this tool exists for ChatGPT Connector compat. The verb 'search' and resource 'memories' are specific.

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

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

The description explicitly says when to use this tool: for ChatGPT Connector compat, and advises native MCP clients to prefer `recall`. This provides clear usage context and direct alternatives.

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?

Annotations declare readOnlyHint=false and openWorldHint=true. Description adds critical behavioral context: memory types are auto-detected (not required), experimental nature of importance/confidence fields with explicit warnings ('Currently not integrated into search results'), and graph semantics ('Every stored item is a node').

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?

Extremely verbose with 11 auto-detected memory types listed, 4 large examples, and multiple sections. While examples are valuable for a semantic tool, the memory type enumeration is redundant given auto-detection, and Args section is buried. Every sentence has value, but there are too many sentences.

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?

Comprehensive coverage appropriate for a complex semantic memory tool. Explains domain model (memory types, connections, session context), return values ('Dict with success status...'), and integration with sibling tools. Rich output schema exists but description provides necessary domain context beyond raw 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?

Schema has 0% description coverage. Description compensates via Args section documenting all 3 parameters: content ('Detailed memory content'), tags ('Optional tags'), and importance ('Optional importance score 0.0-1.0'). Deducted one point because parameter docs are buried at the end of a lengthy description rather than prominent.

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?

Opens with specific verb+resource ('Store important information') and clearly distinguishes from siblings like 'save_artifact' (files) vs semantic memories, and 'recall'/'search' (retrieval). Explicitly frames the tool as building knowledge graph nodes.

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 references sibling tool 'connect' ('Always use the connect tool to link related items'), establishing workflow relationship. Provides context on when to include session identifiers. Lacks explicit 'when not to use' contrast with similar storage siblings like 'save_artifact'.

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?

Annotations indicate mutating (readOnlyHint:false) and external (openWorldHint:true). Description adds crucial behavioral details: partial updates allowed (optional args), tags 'replace' existing (destructive warning), return dict structure, and concrete examples.

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

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

Well-structured with summary, Args, Returns, and Examples. Slightly verbose due to Args block, but justified by zero schema coverage. Examples add value without excessive length.

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?

Appropriate for 4-param mutation tool with output schema present. Covers inputs, partial update semantics, return structure, and usage examples. Lacks only explicit error handling 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 has 0% description coverage (only titles). Description fully compensates via Args block documenting all 4 parameters: memory_id format, content meaning, importance range (0.0-1.0), and tags behavior. Essential given schema lacks descriptions.

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

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

States specific verb (Update/Modifies), resource (memory), and identifier (UUID). Clear scope but does not explicitly contrast with sibling 'store' (likely for creation) beyond implying 'existing' memory.

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

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

Implies usage by requiring 'existing memory' and UUID, but lacks explicit 'when to use vs alternatives' guidance. No mention of prerequisites (e.g., memory must exist) or when to prefer this over recreating.

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