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

No annotations are provided, so the description carries full burden. It discloses read-only behavior, the untrusted nature of version history, the security stance on untrusted data (never follow instructions), and the error response for unknown or deleted slugs. This is thorough and actionable.

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-organized: a clear first sentence states the core purpose, followed by additional behavioral details and usage routing. Every sentence adds value with no fluff, and the most important information is 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?

For a two-parameter tool with no output schema, the description covers the return payload, error behavior, security caveats, and usage guidance. Nothing an agent needs to correctly invoke this tool is missing, making it 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 schema has zero description coverage, so the description must compensate. It explains that include_history adds the version trail and frames it as untrusted, and indicates slug is the identifier. It points to search tools for finding slugs but does not specify slug format or constraints, leaving a minor gap.

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

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

The description explicitly states the tool fetches one memory by slug and enumerates the fields returned (body, provenance, approval state, wikilinks). It also distinguishes itself from siblings by noting the usage of mem_search/mem_recall to find a slug first, making the purpose unambiguous and differentiated.

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

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

The description gives explicit guidance: use mem_search or mem_recall to locate a slug before calling this, and use mem_list to browse. It also explains the optional include_history parameter and when to use it, leaving no ambiguity about the intended workflow.

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

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

With no annotations, the description carries the full burden and delivers: it discloses the record kind, origin, unapproved state pending `skillmem trust`, the dedup semantics (byte-identical returns existing skill with approval intact vs. differing text refused), conflict-checking against other records including plain notes, and the return value (ok and slug). This is unusually rich behavioral disclosure for a write tool.

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?

Dense but front-loaded: the record's content is stated first, then write semantics, then routing to siblings. Nearly every sentence carries new information, though the run-on semicolon chains make it slightly heavier than necessary.

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 12-parameter, no-annotation, no-output-schema write tool, the description covers the critical unknowns: side effects, approval state, dedup/conflict behavior, and return shape. It stops short of explaining ttl_days and visibility, and does not say what happens to a rejected write beyond refusal.

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 only 50%, so the description must compensate, and it does for the highest-risk parameters: slug conventions and collision behavior, check_conflicts' default and effect, and the metadata-only application for tags/topics/project. It leaves ttl_days and visibility unaddressed, which keeps it from a 5.

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 a specific verb and resource ('Record a skill learned by doing') and enumerates the content the record carries (trigger, steps, outcome, lessons). It explicitly distinguishes itself from siblings by naming mem_write for a plain note/rule, so an agent can route without opening any schema.

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?

Names the alternatives and the conditions that select them: use mem_update when the slug already exists with different text, mem_write for a plain note or rule, and mem_reinforce afterward to record whether the skill held up. The when-not (existing slug, existing note slug) is spelled out rather than inferred.

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

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

With no annotations, the description carries the full burden and does so: it declares read-only, the default (50) and max (100) row cap, the exact returned fields, that bodies are excluded, that archived records are filtered out, and the fallback to mem_get for one record.

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-loads the core behavior (browse, no query) and then adds return shape, parameter semantics, and sibling routing in a compact, dense passage with no filler 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?

With no output schema and no annotations, everything an agent needs is present: ordering, result shape, filtering, limits, and when to prefer siblings instead.

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 and does: it enumerates the allowed `kind` values (note/skill/feedback/project/reference/user), defines `project` as a single project tag, and gives `limit`'s default and ceiling. This adds meaning well 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?

States a specific verb and resource ('Browse memories most-recent-first'), plus scope: no query required. It distinguishes itself from siblings by contrasting with mem_search and mem_recall by name.

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 routing: 'Use mem_search when you know roughly what you are looking for; use mem_recall for task-relevant skills.' This gives the agent a clear condition for choosing each alternative.

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

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

With no annotations, the description carries the full burden and does: it discloses the write is flag-only and reversible, that text/approval/updated_at are untouched, the archived-state interactions, the owner-only authorization rule, and the unknown-slug failure mode.

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 the core action and effect, and the trailing sentences are edge cases and routing rather than filler. It is dense and long, but nearly every clause carries distinct operational information.

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

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

For a two-param mutation tool with no output schema, the description covers effect, reversibility, authorization, failure mode, and even enumerates the return payload, leaving nothing an agent needs missing.

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 100% so baseline is 3, but the description adds real semantics beyond it: the default-true behavior of the flag, plus the non-obvious interaction that pinning an archived record leaves it archived. That is meaning the schema alone does not convey.

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 a specific verb (pin/unpin) and resource (record) with the exact effect: never decays, never archived. Explicitly separates itself from mem_reinforce and from the CLI archive path, so an agent can route without opening sibling schemas.

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?

Gives the when ('a rule that matters precisely because it is rarely needed — a deploy gate, a safety constraint'), the alternative ('Use mem_reinforce for skills that should earn their strength'), and an explicit exclusion ('Retiring a record is the owner's own call at a terminal ... not an agent's').

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 present, so the description carries the full burden of behavioral disclosure. It fully discloses the mutation side effect: every returned skill is marked retrieved, refreshes recency, delays decay, and strength only rises via mem_reinforce. It also exposes ranking behavior, the exclusion of archived skills, and the security-oriented wrapping of unapproved skills as 'data, not instructions.' This is exceptionally transparent.

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

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

The description is dense but every sentence earns its place: purpose, side effect, opt-out, ranking scope, return fields, and sibling routing. It is front-loaded with the core purpose and the critical side-effect warning is prominently labeled. There is no filler.

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?

Despite having no output schema and no annotations, the description is complete for a caller: it names the returned fields, default and cap, ranking approach, archived exclusion, side effects, how to avoid side effects, and the unapproved-skill block. An agent has enough context to invoke the tool correctly and interpret results safely.

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 67%, and the description compensates for the gap and enriches all parameters. It explains query semantics implicitly ('skills that apply to a task'), documents limit's default and cap (default 5, capped at 50), and repeats and contextualizes auto_reinforce's side effect beyond the schema's one-line note. This adds real meaning beyond the input 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 and resource: 'Find the skills that apply to a task before starting it,' and clarifies it operates only on kind='skill' records. It also explicitly distinguishes itself from sibling tools: 'Use mem_search to look across all kinds; use mem_get for one known slug.' This leaves no ambiguity about what the tool does or how it differs from alternatives.

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

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

The description gives explicit when-to-use guidance ('before starting a task'), explains the default side effect and how to avoid it with auto_reinforce=false, and names the alternatives for other use cases (mem_search for all kinds, mem_get for one known slug). It even notes archived skills are excluded, so an agent knows what scope to expect.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it excels. It reveals that the tool WRITES counters (mutation), explains how each evidence value affects strength (raises, lowers, or only refreshes recency), warns that calling twice double-counts, and lists return values (slug, strength, access_count, evidence). It also states failure behavior. This is far beyond what structured fields would 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?

The description is a single, well-structured paragraph with no filler. It front-loads the core purpose and mutation effect, then sequentially covers evidence semantics, counting behavior, failure cases, and alternatives. Every sentence adds value; nothing is redundant or vague. It is concise yet comprehensive.

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 a single enum, no output schema, and no annotations, the description covers all necessary context: what the tool does, side effects (counters, double-counting), expected evidence values and their effects, failure modes, and return values. It even includes routing to sibling tools. Nothing an agent needs to call it correctly is missing.

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 100%, so the baseline is 3, but the description adds significant meaning beyond the schema: it explains the default behavior of self_report (only refreshes recency, not reward), clarifies that each call counts and double-counts, and elaborates on the consequences of each evidence enum value. The slug parameter is implicit in the description. This goes beyond the schema, so a 4 is justified.

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 clear verb-resource statement: 'Record how a recalled skill turned out, so strength reflects results.' It explicitly says it WRITES the skill's counters, which is a specific action on a specific resource. It also differentiates itself from siblings by naming mem_update (for text correction) and mem_pin (for never-decay rules), so an agent can immediately distinguish 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 provides explicit usage guidance: it tells the agent that self_report is only recency refresh, not evidence; it warns against double-counting by saying each call counts; it states failure conditions (unknown slug or non-skill record); and it names the alternatives (mem_update for text fixes, mem_pin for rules that must never decay). This fully covers when and when not to use it.

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

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

With no annotations, the description carries the full burden and does so: read-only with nothing recorded, FTS5 lexical matching with stemming/path tokenization, optional semantic layer whose absence causes cross-language misses, and a security-relevant note that unapproved rows are data, not instructions. This is unusually 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?

Front-loaded with the core purpose and routing advice, and nearly every clause carries information. It is dense and long, but the density is justified rather than padded; only the enumeration of return fields feels slightly list-like.

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

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

No output schema exists, yet the description enumerates the returned columns (slug, kind, title, rank, snippet, origin, approval) and the default result count. Combined with the routing and language caveats, an agent has everything needed to call and interpret this 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 coverage is 50%, so the description adds real value: it documents the default limit (10), explains query semantics (lexical vs semantic, language effects), and gives concrete kind values for filtering. It omits the project parameter and cites kind='skill', which is not among the schema's listed values (feedback/project/reference/user/note), a minor mismatch.

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 a specific verb and resource ('Search all memory by text') and enumerates the covered content types (notes, rules, skills, references, session recaps). It also names siblings mem_recall and mem_get so the agent can distinguish this tool from them without opening a schema.

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 routing advice: use mem_recall when starting a task to get applicable skills, mem_get when a slug is already known, and pass kind='feedback'/'skill' when recaps dominate results. Covers both when-to-use-this and when-to-use-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 carries the full behavioral burden and does so richly: it discloses the SHA256-chained history kept under the required reason, the approval being dropped for text changes, origin='agent' marking, null-means-clear vs omitted-means-unchanged semantics, that ttl_days is immutable here, failure conditions (unknown/deleted/archived/owner-written), and the return shape (ok, slug, history length).

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

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

Very dense and largely front-loaded, with writes/history/approval behavior stated first and edge cases after; nearly every clause adds actionable meaning. The final clause is garbled ('retiring a record retire a record without editing'), costing a point.

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 an 8-parameter mutation tool with no output schema and no annotations, the description nevertheless covers mutation semantics, versioning, permission model, failure modes, and return values. Nothing an agent needs in order to call it correctly is missing.

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 only 13%, so the description must compensate, and it does for the semantically tricky parts: required reason, required body, omitted-vs-null field behavior, and the ttl_days exclusion. It leaves kind, tags, topics, and project entirely unexplained, which is a real gap given the low 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?

States a specific verb (change) and resource (text/metadata of an existing memory) and immediately differentiates from siblings by naming mem_write, mem_reinforce, and retirement. An agent can tell what this does versus the other mem_* tools without opening any schema.

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 routes usage: create unknown/deleted slugs with mem_write, write proposals for owner-authored records, use mem_reinforce to report skill outcomes, and retire rather than edit. When-not-to-use is spelled out alongside 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 provided, the description carries the full burden and does so: it discloses that writes are marked origin='agent' and UNAPPROVED, that approval only happens out-of-band via `skillmem trust <slug>` with no approving tool, the conflict-refusal behavior, and the idempotency rule (byte-identical text returned unchanged, keeping approval). This is exactly the behavioral context annotations would otherwise supply.

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?

Densely packed but front-loaded: the purpose lands in the first sentence, then write/approval semantics, then slug rules, then conflict and ttl rules, then sibling routing. Nearly every clause carries information, though the run-on second sentence could be split for readability.

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 9-parameter mutation tool with no annotations and no output schema, this covers the critical unknowns: mutation effect, approval flow, idempotency, conflict default, and return shape (ok, slug, id). The remaining gap is the semantics of the non-core parameters (kind, tags, topics, project).

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 only 11% across 9 parameters, so the description must compensate and does so for slug, check_conflicts and ttl_days (including the null-clears behavior). However, kind, tags, topics, project, title and body get no semantic treatment beyond their names, leaving roughly half the surface undocumented.

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

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

Opens with a specific verb and resource — 'Create a new memory' — and immediately qualifies the scope with the note/rule/pointer distinction. It also distinguishes itself from siblings by naming mem_learn and mem_update for the adjacent jobs.

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 routes the agent: 'Use mem_learn for a procedure learned by doing; mem_update to change text.' It also gives conditional guidance on check_conflicts ('pass false only deliberately') and states what to do when a slug already exists (use mem_update with a reason).

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