instinct

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

Describes side effects (future observations rerouted silently, confidence summed), error condition, and return format. No annotations provided, but description fully compensates.

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 sections, but slightly verbose in docstring style. Could be more concise without losing 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?

Covers purpose, usage, parameters, return values, and error handling. Even references a sibling tool for discovery. Complete for a non-trivial merge operation.

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

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

Schema coverage is 0%, but description provides clear semantics for both parameters: pattern as key to retire, target as canonical key to absorb into.

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 'alias' and resource 'pattern', with specific use case of merging duplicates. Differentiates from sibling tools by explicitly mentioning companion find_duplicates.

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 (merge duplicates), prerequisite (target must exist), and suggests find_duplicates to discover candidates.

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 thoroughly discloses side effects: writes promoted values, runs detect_chains(), rebuilds FTS5 index. It also states idempotency (already-promoted patterns untouched) and details the exact return structure. This fully informs the agent of consequences.

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

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

The description is well-structured with clear sections: action, thresholds, side effects, return value. It is slightly verbose but every sentence adds value. The front-loading is effective.

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

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

Given the complexity and presence of an output schema in the description, the description is complete. It explains the return fields in detail, covers side effects, and provides usage context. No gaps remain for decision-making.

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

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

The tool has zero parameters and schema coverage is 100%. The description provides no parameter info, but none is needed. The description adds value by explaining the tool's behavior without needing parameter 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 re-evaluates pattern levels and promotes based on confidence thresholds with specific rules for each level. It distinguishes itself from sibling tools like detect_chains by noting that detect_chains is invoked internally, and mentions that session_summary calls it automatically, providing context for when to use it.

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 states when to call consolidate: after bulk imports (import_patterns, import_claude_md) or at the end of an agent session. It also notes that session_summary invokes it automatically, giving guidance on when manual invocation is unnecessary. This clearly differentiates from 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?

Despite no annotations, the description fully discloses behavior: scans confidence log, pairs patterns close in time, only appends confidence, safe to run periodically, and explains the algorithm's non-destructive nature. This exceeds what annotations would typically provide.

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: overview, safety note, parameter explanations, return value. Slightly verbose in places but front-loaded with key information. Could tighten minor phrasing.

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 (2 optional params, no annotations, output schema described in full), this description provides comprehensive coverage. No missing details about purpose, usage, parameters, or return values.

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

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

Despite 0% schema coverage, the description explains both parameters in detail, including defaults, practical guidance (e.g., 'Tight chains only' for smaller window), and thresholds. Adds significant meaning beyond the bare schema.

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

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

Description clearly identifies the tool's purpose: mining observation logs to auto-create sequence patterns (A->B). It distinguishes from siblings by specifying it creates new patterns without overwriting, which is unique among sibling tools like 'observe' or 'alias_pattern'.

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?

States 'Safe to run periodically' and 'Does not overwrite existing chains; only appends', providing context for when to use it. However, does not explicitly mention when to avoid using or compare with alternatives like 'trending' or 'suggest'.

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 read-only nature, explains the underlying process of suggest/observe, the confirmation rate logic, and clarifies that an empty patterns list is not an error. This fully compensates for the lack of 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 well-structured: a concise one-line summary, followed by mechanism, sibling differentiation, parameter details, and return format. 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?

For a tool with one parameter and no annotations, the description covers purpose, behavior, parameter, return format, and edge cases (empty list). The inclusion of the output schema in text makes it 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?

The single parameter 'days' is described in the Args section with default value (30) and guidance for choosing short (7) or long (90) windows. This compensates for the 0% schema description coverage.

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: 'Measure how often suggested patterns were reinforced by a later observe().' It explains the mechanism linking suggest() and observe(), and distinguishes itself from siblings like trending() and stats().

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 alternatives: 'For a raw observation-velocity view use trending(days). For promotion/level distribution use stats().' It also explains the meaning of high/low confirmation rates, guiding when to use pruning actions.

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?

Describes read-only operation, output structure (bullet per rule with key, category, confidence count, explain text), and return type. No annotations exist, so description fully carries behavioral disclosure.

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 purpose, usage, and output sections. Slightly verbose in middle paragraph, but front-loaded and 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?

Complete for a zero-parameter tool: covers purpose, usage, output format, return type, and alternatives. No missing context given simplicity.

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

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

Zero parameters, so baseline is 4. Description does not add parameter info, but none is needed. Focus on output 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?

Clearly states it renders rule-level patterns into Markdown for CLAUDE.md, specifying verb, resource, and output format. Distinguishes from siblings like inject_claude_md and export_platform.

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 when to use (when a compact Markdown block is needed for manual inclusion) and what it does not do (no file modification, only promoted rules). Provides alternatives for idempotent injection and multi-platform export.

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?

Despite no annotations, the description discloses return format (dict with keys content, format, rule_count), behavior on unknown values (rejected via validation), and edge case of empty content. This provides comprehensive behavioral insight beyond what annotations would offer.

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 sections for purpose, usage context, args, and returns. Every sentence adds value; no redundant phrasing. Information is front-loaded with purpose, then detailed guidance.

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

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

Given the tool has one optional parameter and an output schema, the description fully covers input possibilities, output shape, error handling, and usage differentiation from siblings. It is complete for effective tool selection and invocation.

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

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

Schema coverage is 0% but the description lists all valid values for 'fmt' and explains validation behavior, adding meaning absent from the schema. The note about 'Unknown values are rejected by validation instead of silently guessing' provides critical usage guidance.

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 renders rule-level patterns into target editor config formats, listing specific platforms like Cursor, Windsurf, Codex. It distinguishes from siblings like export_claude_md and export_skill by specifying when to use each.

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 when to use (for rules in a specific platform's file) and when to prefer alternatives, e.g., 'prefer export_claude_md() when you only need Claude's CLAUDE.md shape.' Provides clear context for non-Claude targets.

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 declares the tool as read-only and takes no parameters, which is a key behavioral trait. It also details the return format, including the structure of each record and the meaning of an empty 'rules' array. With no annotations provided, the description fully covers the behavioral aspects.

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

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

The description is well-structured with a clear main statement, then usage guidelines, then return format in a bulleted list. Every sentence provides unique value, and the information is front-loaded. Despite its length, it remains focused and efficient.

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

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

Given that the tool has no parameters, no annotations, but has a detailed output schema provided in the description, the description is fully complete. It covers purpose, usage, return format, and edge cases (empty results), leaving no gaps for an AI agent to misunderstand.

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?

There are zero parameters, and the schema description coverage is 100% (since no params exist). The description adds context by stating that the tool takes no parameters, which is sufficient. According to guidelines, baseline for 0 parameters is 4.

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 action ('Export'), the resource ('promoted-level patterns (rule + universal)'), and includes a specific threshold (promoted >= 2). It also differentiates from sibling tools by naming alternatives like export_claude_md, export_platform, export_skill, and list_instincts.

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 states when to use this tool ('for programmatic consumption: analytics pipelines, sibling agents, external dashboards') and provides clear alternatives for other use cases (human-readable Markdown, platform-specific formats, lower-confidence audits). It also notes that if no patterns have reached rule level, the hint directs to run consolidate() first.

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 provided, so description carries full burden. It declares 'Read-only', details return values for success and empty store, and explains the hint about prerequisites. No contradictions.

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 purpose first, then alternative guidance, parameter docs, and return value. Slightly verbose but every sentence adds value. Could be tightened slightly.

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 3 params, no nested objects, and existence of output schema, the description covers all necessary context: parameters, usage, prerequisites, return values, and edge cases. Complete for effective use.

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

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

Schema description coverage is 0%, but description provides detailed explanations for all 3 parameters (name, description, category) including default behavior and allowed values, going well 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 uses a specific verb 'Package' and resource 'rule-level patterns' outputting a SKILL.md file. It clearly distinguishes from siblings by naming alternative tools (export_claude_md, export_platform, export_rules).

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 this tool vs alternatives with references to other functions. Also describes behavior on empty store, directing user to consolidate() as prerequisite.

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

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

No annotations are provided, so the description carries the full burden. It states 'Read-only — this tool suggests merges but never performs them,' disclosing the behavioral trait. It also outlines the comparison logic and return structure, though more details on limitations could be given.

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

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

The description is well-structured with clear sections, front-loading the main purpose. It is concise yet informative, with no wasted 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?

Given the tool's simplicity (one parameter, read-only, complete output schema), the description covers all essential aspects: purpose, usage context, parameter semantics, and return value. It references sibling tools appropriately.

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 coverage is 0%, but the description fully explains the threshold parameter: its range (0.0-1.0), default (0.75), effect on sensitivity, and tuning advice. This adds significant meaning beyond the bare schema.

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

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

The description clearly states the tool's purpose: 'Detect near-identical pattern keys that should probably be merged.' It uses a specific verb ('detect') and resource ('pattern keys'), and the context of merging distinguishes it from sibling tools like alias_pattern.

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 a common use case: after bulk import_patterns() or import_claude_md(). It also notes the tool is read-only and suggests using alias_pattern for actual merging. However, it does not explicitly mention when not to use this tool or 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?

Despite no annotations, the description explains each step and asserts safety and idempotence. It discloses that it removes orphan aliases and rebuilds FTS, covering key behaviors without contradictions.

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

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

The description is well-structured with a summary, bullet steps, safety note, parameter explanation, and return format. It is front-loaded and each sentence is useful, though slightly verbose.

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

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

With an output schema present and only one parameter, the description covers return dict keys and parameter semantics. It also provides context on housekeeping and tool discoverability, making it complete for the tool's complexity.

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

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

Schema coverage is 0%, but the description fully explains the single parameter dedup_threshold, including range, default, and reference to find_duplicates() for tuning notes, adding significant value beyond the schema.

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

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

The description clearly identifies the tool's purpose: running all store-maintenance tasks in one call. It enumerates the four specific steps (decay, dedup, orphans, FTS) and distinguishes it from siblings like find_duplicates() and alias_pattern().

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 the tool is safe and idempotent, and notes that finer control is available via individual tools. Also recommends housekeep() for discoverability, providing clear guidance on when to use this tool versus 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?

With no annotations, the description fully discloses behavior: exact-match, case-sensitive, read-only, requires category prefix, returns full record on hit or error on miss, and instructs callers to check for error key. Provides rich 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?

The description is well-structured with sections, bullet points, and examples. While slightly verbose, every sentence adds value; could be slightly more concise but remains 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 the single parameter and existence of output schema, the description is thorough: covers input format, return structure, error handling, and usage context. Leaves no gaps for a simple lookup tool.

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

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

Schema coverage is 0%, but the description provides extensive detail: examples of valid patterns, case-sensitivity, requirement for category prefix. This adds critical meaning beyond the bare schema.

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

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

The description clearly states 'Fetch the full record for one pattern by its exact key,' which is a specific verb+resource combination. It distinguishes from sibling tools like search_instincts and list_instincts by contrasting exact-match versus substring search or browsing.

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 (after suggest() returns a compact entry) and when to use alternatives (search_instincts for substring, list_instincts for browsing, history for confidence timeline). Provides 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?

No annotations are provided, so the description carries the full burden. It describes the return format and that it is a read-only query of observations. There is no mention of error handling, rate limits, or authentication, but for a read tool the disclosures are adequate.

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

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

The description is well-structured with clear sections (Args, Returns) and front-loads the purpose. Every sentence adds value without wasting words. It is appropriately sized for the tool's simplicity.

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

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

Given the tool has a simple input schema, no annotations, and an output schema, the description provides all necessary context: what it does, how to use it, and what to expect. It also distinguishes from sibling tools, making it complete for agent use.

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

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

Schema description coverage is 0%, so the description must compensate. It adds detailed semantics for both parameters: 'pattern' is explained as an exact case-sensitive key with prefix, and 'days' is described as a look-back window with default 30. This adds significant meaning 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 states the tool's purpose: 'Show how one pattern's confidence evolved over a time window.' It uses a specific verb and resource, and distinguishes itself from the sibling tool get_instinct (snapshot vs. timeline).

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 tells when to use this tool (for timeline/history) and when not ('For a snapshot of the current state...use get_instinct() instead'). It does not cover all possible alternatives, but provides strong context.

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

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

With no annotations, the description reasonably discloses behavior by listing operations and return value structure. It states it's 'safe to run periodically,' but could mention potential irreversible effects more explicitly.

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

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

The description is concise, with a clear bullet list of operations, usage note, and parameter description. Front-loaded main purpose. Could be slightly more streamlined but effective.

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

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

Given the tool's complexity (multiple operations) and existence of output schema (return keys listed), the description is fairly complete. However, it omits potential preconditions or asynchronous behavior.

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 fully explains the single parameter 'dedup_threshold': range (0.0-1.0), default (0.75), and reference to find_duplicates() for tuning, adding significant meaning 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 states the tool's purpose with specific verbs and resources: 'Run cleanup, deduplication, decay, orphan cleanup, and FTS rebuild.' It also distinguishes itself from the sibling 'gc' by noting they are identical.

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 tells when to use: 'Use this when you want to clean up, housekeep, prune stale patterns, or rebuild search after many observations or imports.' Also notes it's safe to run periodically and is an alias for gc.

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 read-only nature ('the source file is not modified'), extraction details (confidence counts, explain text), and return dict keys. No annotations present, so description carries full burden and does well.

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

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

Description is concise with a clear head sentence and detailed follow-up. Could be slightly more front-loaded, but no unnecessary 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?

Given a simple tool with one parameter, no annotations, and an output schema, the description thoroughly covers purpose, usage, behavior, and return values. Complete for the 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?

Single parameter 'source' has 0% schema description coverage. Description adds 'Path to the CLAUDE.md file', providing essential meaning. Minimal but adequate for a simple string path.

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 parses a CLAUDE.md file and ingests backtick-wrapped patterns, with a specific verb and resource. It distinguishes itself from siblings like export_claude_md and inject_claude_md.

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 (bootstrap or sync rules). Does not mention alternatives or when not to use, but context from siblings provides differentiation.

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 provided, so description carries full burden. Explains behavior: each row routed through observe(), confidence incremented but never lowered, rows with missing pattern skipped. Discloses mutation and return structure with counts and hint.

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?

Description is well-structured with sections for purpose, parameters, and returns. Front-loaded with main action. Slightly verbose but every sentence adds value. Could be trimmed slightly without loss.

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 tool complexity (bulk insertion with merging logic) and no annotations, description covers all essential aspects: behavior, parameter details, return format, and relationship to siblings. Output schema described in text. Complete for agent use.

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

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

Input schema has 0% coverage (only specifies array of objects with no properties). Description fully compensates by detailing required keys ('pattern'), optional keys with defaults and types (category, source, project, metadata, explain, confidence), and their 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?

Description clearly states 'Bulk-insert many patterns in a single call; faster than looping observe()', specifies verb and resource. Distinguishes from sibling tools like observe and import_claude_md by noting performance advantage and specific use case for Markdown imports.

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 tells when to use (bulk insert, faster than observe) and when not (use import_claude_md for Markdown files). Recommends consolidate() after large import, providing clear context and 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?

With no annotations, the description bears full responsibility. It discloses idempotent writes, marker-based partial updates, file creation if missing, and the return dict. It notes the prerequisite that parent directories must exist, but does not cover all potential side effects (e.g., permission issues) – a minor gap.

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

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

The description is well-structured with a leading one-sentence summary, followed by detailed behavior, an alternative tool mention, and structured Args/Returns sections. Every sentence provides essential 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 the tool's simplicity (one parameter, no nested objects, output schema indicated), the description covers purpose, usage, behavioral constraints, and return values thoroughly. However, it omits explicit error cases (e.g., missing parent directories would cause failure) and does not define 'rule-level patterns', assuming domain knowledge. Minor completeness gaps exist.

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

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

The sole parameter 'target' has 0% schema description coverage, so the description must compensate. It does so thoroughly: explains it is an absolute or relative path, that the file itself will be created, and that parent directories must exist. This adds significant meaning beyond the schema type.

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

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

The description explicitly states 'Idempotently write rule-level patterns into a CLAUDE.md file' with a clear verb and resource. It distinguishes itself from the sibling tool export_claude_md by noting it modifies files versus one-shot rendering without filesystem impact.

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

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

The description provides clear context: it is safe to run on every commit or session end, and it suggests using export_claude_md for one-shot rendering. It also explains idempotency and the marker-based block update, offering explicit usage guidance.

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

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

With no annotations provided, the description carries the full burden. It declares read-only behavior and sorting order, and notes that low-confidence observations are included. However, it does not mention rate limits or any other behavioral constraints.

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

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

The description is well-structured with sections and front-loaded purpose. While informative, it is slightly verbose with detailed parameter explanations; a more concise version could still be effective.

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

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

Given the tool has 4 parameters, no required params, and an output schema, the description covers purpose, usage, parameters, return structure, and next-step hints. It is fully sufficient for an AI agent to select and use the tool correctly.

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

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

Schema description coverage is 0%, but the description thoroughly explains each parameter: min_confidence with examples, category with allowed values, project with fingerprint explanation, and limit with default and usage. This adds significant meaning 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 states the tool lists recorded patterns with filters including low-confidence observations, and distinguishes itself from siblings like suggest(), search_instincts(), and get_instinct() by contrasting scope and use cases.

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

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

The description provides explicit guidance on when to use this tool vs alternatives: 'For day-to-day agent guidance prefer suggest(). For keyword search use search_instincts(). For a single exact-key lookup use get_instinct().' It also lists specific use cases like audits and debugging.

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 provided, but description fully discloses behavioral traits: idempotent on pattern key, confidence levels (1=new, 5=mature, 10=rule), return values. It adds context beyond what structured fields could convey.

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 sections for purpose, usage, args, returns. Each sentence adds value. Slightly verbose but front-loaded and clear. Could tighten a few phrases without loss.

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

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

Given no annotations, complex behavior, 5 parameters, and output schema, description is very complete. Covers when to use, parameter details, idempotency, return values, and conventions. Output schema exists but description explains return dict structure.

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%, but description explains each parameter with examples and conventions (e.g., pattern key format, category default, source and project usage). Adds significant meaning beyond bare schema properties.

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

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

Description clearly states the tool records an observation of a behavioral pattern and increments confidence. It distinguishes from siblings by specifying it is for patterns that may recur, not one-off notes, and uses specific verbs like 'record' and 'log'.

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 when to use (log anything for agent learning) and when not to (one-off notes belong in regular memory). Provides guidance on repeated calls to raise confidence and contrasts with sibling tools like `alias_pattern` or `consolidate`.

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 read-only nature, FTS5 behavior, automatic fallback to LIKE, and return format. With no annotations, this covers key traits effectively, though potential issues like timeouts are not mentioned.

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 sections and examples, but slightly verbose; every sentence adds value, but could be tightened slightly.

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

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

Covers search behavior, syntax, fallback, return schema, ordering, and fallback next steps, making it fully self-contained 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 coverage is 0%, but the description explains the query parameter with FTS5 syntax and the limit parameter with default and usage guidance, adding substantial 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?

The description clearly states it finds patterns by keyword across specified fields and distinguishes from sibling tools (get_instinct, list_instincts).

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 alternatives: 'For exact-key lookup use get_instinct(). For unfiltered browsing or category/project filters without a keyword, use list_instincts().' Also advises on limit adjustments.

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 side effect: runs consolidate() and rebuilds FTS search index. Lacks details on auth or error handling, but adequately covers behavioral impact.

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 for purpose, usage, side effect, args, returns. Slightly verbose but each sentence adds value; front-loaded.

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

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

Covers purpose, side effect, parameters, and return keys. Differentiates from siblings. Could mention edge cases or failure modes, but sufficient for typical use.

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

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

Adds meaning beyond schema: 'Project fingerprint to scope the summary. Empty string auto-detects from cwd (recommended).' Explains purpose and default behavior.

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 'End-of-session snapshot' and 'one-call overview' for session log or memory append. Distinguishes from siblings like stats and suggest by noting the side effect.

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 'Call this at the end of an agent session' and provides alternative: 'If you want a pure read-only summary, use stats() + suggest() separately.'

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?

Despite no annotations, the description is fully transparent: 'Read-only; no side effects; no params.' It also explains empty store behavior and return structure, leaving no hidden 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 highly concise: a brief purpose statement, then usage guidelines, then a clear return spec. Every sentence earns its place without repetition or fluff.

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

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

For a parameterless tool with an output schema, the description is complete: it covers all relevant aspects (purpose, usage, behavior, return details, edge cases), leaving no 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?

No parameters exist, so schema coverage is 100% trivially. The description adds value by detailing return fields and their relationships (e.g., level partition sums to total), which goes beyond the output schema alone.

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 'Summary of the instinct store' and lists specific metrics (totals, level distribution, category breakdown). It explicitly distinguishes from siblings by naming trending and session_summary as alternatives, fulfilling 'specific verb+resource, distinguishes from siblings'.

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 guidance: 'Use for a quick health check' and states when to use trending or session_summary instead. This gives clear context and exclusion criteria.

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?

Description reveals sorting order (by confidence descending), filtering behavior (empty strings return all), defaults, and return structure. With no annotations, it fully discloses behavioral traits, including the hint pointing to get_instinct for details.

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 sections for usage, args, and returns. Slightly lengthy but every sentence adds value. Could be more concise, but still effective.

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

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

Given 4 parameters, no annotations, and an output schema, the description fully covers input/output behavior, usage context, and distinguishes from a key sibling. Sufficient for an agent to use 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 are explained with semantics beyond the schema (which lacks descriptions). 'project' handling of empty string, 'category' enum values, 'keyword' substring matching, and 'compact' token counts are all detailed.

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

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

Description clearly states the verb 'Retrieve' and resource 'mature patterns (confidence >= 5)' and distinguishes itself from sibling 'list_instincts' by noting it returns only validated patterns, not seedlings.

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 advises when to call ('at the start of a task'), what to expect ('learn how similar work has been handled before'), and when to prefer alternatives ('Prefer this over list_instincts... use list_instincts to see seedlings'). Also clarifies compact vs full modes.

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 provided, but description fully discloses read-only behavior, fallback path, and return structure including extra field and its absence. Comprehensive 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?

Front-loaded with key point. Every sentence adds value, but slightly lengthy. Could be trimmed slightly without losing 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?

Output schema exists, but description complements it with detailed return format explanation, including extra field and fallback behavior. Complete and comprehensive.

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

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

Schema coverage is 0%, but description adds extensive semantics: days explains window size for hot vs steady, limit explains max patterns and ordering. Adds significant value beyond 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 ranks patterns by observation velocity (reinforcements per window). It distinguishes itself from sibling tools like list_instincts (all-time leaderboards) and effectiveness (confirmation rate).

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: use for ranking by velocity, fallback ordering. Alternatives named: list_instincts for all-time, effectiveness for confirmation rate. Parameter guidance: days window size for hot vs steady patterns.

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