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

With no annotations, the description carries the burden; it discloses return fields (body, provenance, wikilinks), the version-trail behavior, and a critical trust/safety rule about untrusted memories. It does not cover all edge behaviors, but key traits are explicit.

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?

Purpose is front-loaded, and the description is structured from action to return details to parameter option to safety caveat. The safety warning is long but essential and 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?

Given no output schema and no annotations, the description covers the core return structure, parameter behavior, and a non-obvious trust caveat. It is sufficiently complete for the agent to invoke correctly, though alternative selection guidance is absent (already scored separately).

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%, so description must explain parameters. It clarifies that slug identifies the memory and explains the effect of include_history=true. This adds 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?

States a specific action ('Fetch one memory by slug'), which clearly distinguishes it from sibling tools that search or list memories. The resource and identifier are precise, so the agent can tell exactly what this tool does.

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 guidance on when to choose mem_get over mem_search, mem_list, or mem_recall. The only usage note concerns include_history, which is parameter-level, not tool selection.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions storage as kind=skill and Ebbinghaus strength tracking, but does not disclose whether this is a destructive write, how conflicts are handled (despite a check_conflicts parameter), or any permission requirements. The description adds minimal behavioral context beyond its stated purpose.

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

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

The description is a single, well-structured sentence that front-loads the primary purpose and adds a relevant storage detail. It is appropriately concise with no wasted words.

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

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

Given 12 parameters, 50% schema coverage, no annotations, and no output schema, this description is insufficient. It does not explain return behavior, conflict handling, or provide enough guidance for an agent to correctly populate all parameters or choose this tool over siblings.

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 50%, so half the parameters lack schema documentation. The description mentions the core fields (trigger, steps, outcome, lessons) but does not explain tags, topics, project, ttl_days, visibility, or check_conflicts. It adds some value for the key fields but does not fully compensate for the undocumented half.

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 verb (record) and resource (after-action skill), and specifies it stores as kind=skill with Ebbinghaus strength tracking, which distinguishes it from generic write tools like mem_write. However, it does not explicitly name sibling alternatives or state what it is not for, so it falls short of a 5.

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

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

The description implies usage for task experience and lessons learned, but does not explicitly state when to use it versus alternatives like mem_write or mem_update. There is no mention of exclusions or when to prefer other tools, so guidance is only implied.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states ordering ('most-recent-first') and optional filters, but doesn't disclose pagination behavior, what 'kind' and 'project' mean, whether the list is bounded, or what the return format looks like. For a read tool, the lack of annotation coverage makes this a significant 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 a single, efficient sentence that front-loads the core behavior ('List memories most-recent-first') and then mentions optional filters. No wasted words, though it could have added a bit more useful detail without becoming 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?

For a list tool with no annotations, no output schema, and 0% schema description coverage, the description is too thin. An agent doesn't know what 'kind' values are valid, whether 'limit' is capped, how results are returned, or how this differs from mem_search and mem_recall. The sibling set is large, and the description doesn't help disambiguate.

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 mentions 'kind' and 'project' as filter dimensions, which adds some meaning, but it doesn't explain the valid values for 'kind' or how 'limit' interacts with the ordering. The description adds minimal value beyond the schema's bare property names.

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 states a specific verb ('List') and resource ('memories') with a clear ordering ('most-recent-first'), which distinguishes it from sibling tools like mem_get (single retrieval) and mem_write (creation). It doesn't explicitly name a sibling, but the list/retrieve/write distinction is clear enough.

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 usage for browsing memories with optional filters, but it doesn't explicitly state when to use this tool versus mem_search or mem_recall. The 'Optionally filter by kind or project' gives some context, but there's no explicit when/when-not guidance or 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?

With no annotations, the description carries the full burden and largely delivers: it discloses the core behavioral effect (protection from decay and archival) and reversibility (unpin). It does not detail secondary effects on retrieval or permissions, but the primary state-changing behavior is 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?

Two sentences: the first states the action and effect, the second provides a rationale with concrete examples. Each sentence earns its place; the rationale may be slightly stylized, but it remains compact and informative.

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 2-parameter tool with no output schema, the description covers the essential state change (pin/unpin), the effect (no decay/archive), and a plausible use case. Minor omissions (e.g., exact interaction with memory retrieval) are acceptable given 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 description coverage is 100%, with both parameters already documented ('slug' and 'pinned' including default behavior). The tool description adds no additional parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

Clearly states the verb ('pin'/'unpin'), the resource ('skill'), and the effect (never decays, never archived). The purpose is distinct from all sibling tools, which perform search, retrieval, writing, updating, learning, and reinforcement.

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 clear contextual guidance: it explains when pinning is appropriate ('a deploy gate, a safety constraint') and why it matters for rarely-needed rules. It does not explicitly name alternatives or offer when-not-to-use exclusions, but the context is sufficient for an agent to decide.

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 disclosure burden. It transparently reveals the key side effect: 'Auto-reinforces retrieved skills.' It also explains the ranking behavior, which is important for interpreting results. It could mention that reinforcement can be disabled via the auto_reinforce parameter, but the schema already documents that.

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

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

Two concise, dense sentences deliver the purpose, context, ranking mechanism, and side effect without any filler. The information is front-loaded and every sentence earns its place.

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

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

The description covers purpose, ranking, and side effects, but there is no output schema and the description does not explicitly state what the tool returns, how limit affects results, or that auto_reinforce can be disabled. An agent would need to infer the return shape from the word 'Find.'

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

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

The description adds ranking semantics beyond the schema, such as BM25 and Ebbinghaus weighting, which enriches the meaning of 'query.' However, it does not explain the limit parameter, and the auto_reinforce behavior is already described in the schema. With 67% schema coverage, the description partially compensates but not fully.

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 action ('Find relevant skills'), the context ('before starting a task'), and the unique retrieval mechanism (BM25 relevance weighted by Ebbinghaus strength). This distinguishes mem_recall from generic search tools like mem_search and from reinforcement-specific tools like mem_reinforce.

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 frames the tool as a pre-task step, giving clear context for when it should be used. However, it does not name sibling alternatives like mem_search or provide explicit 'when not to use' guidance, though the auto-reinforcement note indirectly signals that it replaces a separate reinforce step.

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 of behavioral disclosure. It clearly explains that strength only rises on external evidence, that self_report merely refreshes recency, and that failure lowers strength. This is substantial, non-obvious behavior that an agent needs to know before calling the 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?

Two sentences deliver the core purpose and the critical evidence rule with no filler. The most important constraint — external evidence only — is front-loaded and immediately actionable. Every sentence earns its place.

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

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

For a simple two-parameter tool with no output schema, the description gives an agent enough to call it correctly: what to pass, what each evidence value means, and the behavioral consequences. It could mention what the tool returns or whether reinforcement is reversible, but those are minor gaps given the schema already covers parameters.

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

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

Schema description coverage is 100%, so the schema already documents both parameters and explains each evidence enum value. The description restates the evidence semantics but adds little beyond the schema; it does clarify that 'saying it helped is not evidence,' which reinforces the self_report default. This meets the baseline for high schema 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 opens with a specific verb and resource: 'Record how a recalled skill turned out.' It clearly conveys the tool's role in reinforcement, and the evidence-based strength adjustment distinguishes it from generic mem_write/mem_update. It does not explicitly name sibling alternatives, so it falls just short of a 5.

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

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

The description implies when to use it — after recalling and applying a skill, to record the outcome. It gives meaningful guidance on what counts as valid evidence, but it does not explicitly state when to prefer this over mem_update or mem_learn, nor does it state exclusions. Usage context is clear but left mostly to inference.

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

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

No annotations are provided, so the description carries the full burden. It discloses the search algorithm (FTS5 BM25), the fields searched (titles, bodies, tags, topics), stemming languages, and the return format (top-N results with rank and snippet). This goes beyond the schema and provides useful behavioral insight. However, it does not explicitly state that the operation is read-only or non-destructive, which is a minor gap given 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 two sentences, highly concise, and front-loaded with the core purpose. It packs the search scope, algorithm, stemming, and return details into minimal words without redundancy. Every clause adds value.

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

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

Given the tool has 4 parameters, no output schema, and no annotations, the description covers the search mechanics and return format but omits important context like how to use the project filter, default limit behavior, pagination, or read-only nature. For a search tool this is adequate but not exhaustive; an agent could call it correctly for simple queries but might misjudge filter usage or limit semantics.

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

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

Schema description coverage is only 50% (query and kind have descriptions; limit and project do not). The description mentions 'top-N results', which loosely hints at the limit parameter, and the search scope implies the query parameter, but it does not explain the project filter or how limit controls N. With half the parameters undocumented, the description should compensate but fails to fully do so, particularly for project which is completely absent from the text.

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 'Full-text search across skillmem memory', which is a specific verb-resource pair. It distinguishes itself from sibling tools like mem_get (retrieval by ID) and mem_list (listing) by focusing on search. It also adds technical specifics (FTS5 BM25, stemming) that reinforce its unique role.

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 usage for searching but does not explicitly state when to use this tool versus alternatives. There is no mention of 'use this when you need to search' or exclusions like 'for exact ID lookup use mem_get'. The purpose is clear enough, but the lack of explicit routing guidance means the agent must infer context.

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

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

The description discloses meaningful side effects beyond simple mutation: old body preservation, the role of the supplied reason, and a full birth/expiration/death trail. Since no annotations are present, this behavioral context is especially valuable, though permissions, reversibility, and other side effects remain unaddressed.

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

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

Two sentences deliver the core purpose and the most important behavioral side effect without wasted words. The content is front-loaded and each sentence earns its place.

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

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

With nine parameters, no annotations, no output schema, and only 11% parameter documentation, this description is too thin to fully guide an agent. It captures the central update-and-preserve behavior, but omits return behavior, prerequisites, optional-field semantics, and failure conditions.

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%, so the description must compensate, but it only lightly covers 'body' and 'reason' while leaving slug and all optional fields unexplained. The identification role of slug is implicit at best, and fields like kind, tags, agent, title, topics, and project receive no semantic elaboration.

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 states a specific action ('Update an existing memory') with a clear resource, and adds a distinguishing behavioral detail: the old body is preserved in memory_history. It doesn't explicitly name sibling alternatives, but the word 'existing' differentiates it from mem_write.

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 'existing memory' implies the tool is for updating rather than creating, but there is no explicit when-to-use or when-not-to-use guidance against siblings like mem_write, mem_learn, or mem_reinforce. An agent is left to infer selection criteria from the verb alone.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states slug uniqueness, the refusal to overwrite, and the provenance rationale, which are the key behavioral traits. However, it does not mention the default check_conflicts behavior (Jaccard overlap rejection), which could cause unexpected failures. This is a notable gap but the most important behavioral differentiator is disclosed.

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

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

The description is two tight sentences with zero filler. The primary action ('Insert a new memory') is front-loaded, immediately followed by the unique constraint and the routing rule. Every sentence earns its place and there is no redundant 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?

The description covers the critical insert-versus-update decision and the uniqueness constraint, which is enough for common calls. However, with 10 parameters, no output schema, and no annotations, an agent would benefit from more context about return values, error behavior, and valid values for fields like kind or ttl_days. It is adequate but has clear gaps.

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

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

Schema description coverage is only 10% (only check_conflicts has a description), and the main description adds almost no parameter semantics beyond the uniqueness constraint on slug. Parameters like kind, agent, project, topics, and ttl_days are left undefined, relying on the agent to infer their meaning from names. The description does not compensate for the low schema 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 opens with a specific verb and direct object: 'Insert a new memory.' It immediately clarifies the operation's scope (new memory, not update) and distinguishes itself from the sibling tool mem_update by explicitly routing overwrite scenarios elsewhere. This is precise and leaves no ambiguity about the tool's core function.

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

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

The description explicitly states when to use an alternative: 'To overwrite an existing slug, use mem_update with a reason.' It also explains the reasoning (deliberate refusal to silently overwrite) and implies mem_write is only for new unique slugs. This gives an agent a clear decision rule without needing to infer.

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