crewmemory

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

No annotations are provided, so the description must disclose behavioral traits. It adds the ownership constraint, which is a key behavioral detail. However, it does not mention whether the deletion is permanent, reversible, requires authentication, or has any side effects. For a deletion operation with zero annotations, more context would be expected, but the simplicity of the tool partially mitigates the 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 two sentences with zero wasted words. The core purpose and the key usage constraint are front-loaded, and the alternative tool is mentioned directly. Every sentence earns its place, making it an efficient and well-structured description.

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 tool is simple (single parameter, no nested objects), and an output schema is present, so return values are covered elsewhere. The description provides the essential operational context: what it does, ownership condition, and when to use it. However, it lacks explicit parameter meaning and any mention of prerequisites or side effects, which leaves minor gaps for an agent to resolve. Given the simplicity, it is adequate but not exhaustive.

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 no description for entry_id, and the description does not explicitly explain what entry_id represents or how to obtain it. It implies the ID relates to the memory entry, but does not specify its format, source (e.g., from search_memory), or that it must belong to the user. Given 0% schema coverage, the description should compensate but does not, leaving the agent to infer the parameter's 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 the tool's function with a specific verb ('Delete') and resource ('your own memory entry'), and explicitly distinguishes it from the sibling tool mark_superseded by defining the ownership scope. This makes it easy for an agent to select correctly among the many sibling tools.

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

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

It explicitly states when to use this tool (for your own memory entries) and provides an alternative ('For other people's entries use mark_superseded instead'). This is a model example of usage guidance—clear, actionable, and eliminates ambiguity about 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, the description must carry the full behavioral burden. It discloses that the tool returns commit messages, authors, and timestamps, which is useful context for a read operation. However, it does not state whether it is strictly read-only, if there are any auth or rate limitations, or any side effects, which is a gap given the lack of annotation coverage.

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?

A single, well-structured sentence that ends with a colon, implying the result, and front-loads the key information (provenance). Every word earns its place; there is zero fluff or redundancy.

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

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

The tool has a simple signature with a single parameter and an output schema, so the description does not need to detail return formatting. However, it does not explicitly state what constitutes a 'memory' or how the entry_id is tied to git history, which could be important for correct invocations in a broader context. Overall, it's adequate but leaves a few semantic gaps.

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

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

The schema covers 0% of parameter meaning, so the description must explain the 'entry_id' parameter. It does not mention what format or identifier is expected, or how it relates to the memory entry. The description only alludes to 'this memory' without clarifying the parameter, leaving agents to infer from the schema's bare title.

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 a specific purpose: to retrieve the provenance (git commit history) of a given memory entry, specifying who, when, and why. It effectively distinguishes itself from siblings like 'recall' or 'get_memory' by focusing on commit-level history rather than content or status.

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 (when you need to inspect the commit history of an entry) but does not explicitly state when to use it vs. alternatives like 'git_blame_context' or 'why_code'. It does not provide exclusions or conditions for when not to use it, leaving some inference to the agent.

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 indicates the tool detects duplicates (implying a read-only operation) and specifies detection criteria (similar titles or linked files), which is useful. However, it does not explicitly state that the tool does not modify anything, nor describe the output structure or any side effects. The description does not contradict annotations (there are none) but falls short of full transparency.

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, front-loaded sentence that immediately states the action ('Detect'), resource ('duplicate/overlapping memories'), criteria, and purpose. There is no fluff or redundant detail; every word earns its place. It is both concise and well-structured for quick agent comprehension.

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 (0 parameters) and the presence of an output schema (which covers return format), the description is adequately complete for calling the tool. It explains what the tool does, how it identifies duplicates, and why it is used. The only missing element is an explicit statement about the output structure, but that is handled by the output schema. Overall, an agent has sufficient context to use 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?

The tool has zero parameters, so the baseline is 4. The description does not need to add parameter semantics because there are none to explain. No further information is required in the description for this dimension.

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 and resource: 'Detect duplicate/overlapping memories' with clear detection criteria ('similar titles or same linked files'). It also conveys the purpose ('so they can be consolidated'), making the tool's intent unambiguous. Among sibling tools like search_memory or recall, this is clearly distinct as it targets duplicates for consolidation, not general retrieval.

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

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

Usage is implied through the purpose ('so they can be consolidated') – an agent understands this tool is for finding duplicates prior to consolidation. However, the description does not explicitly state when to use this tool over alternatives (e.g., vs search_memory) nor provides any exclusions. It lacks explicit 'when to use' or 'when not to use' guidance, so it falls into the 'implied usage' category.

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 key behavior: stale entries are down-ranked heavily. However, it does not mention reversibility, permissions, or side effects beyond down-ranking. For a simple flag operation, this is a valuable disclosure but not exhaustive.

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 sentences front-load the core action and effect. Every word earns its place, with no redundant phrases or 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?

Given the tool's simplicity (one required parameter) and the presence of an output schema (which handles return details), the description covers the essential behavior. It does not mention error conditions or permissions, but these are arguably not critical for such a lightweight operation, and the output schema likely covers response 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 coverage is 0%, so the description must clarify the parameter semantics, but it makes no mention of entry_id at all. The meaning of the parameter is obvious from its name and schema, yet the description adds zero value, failing to compensate for the schema's lack of description.

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

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

The description states a specific verb ('flag'), a resource ('a memory'), and a clear condition ('probably wrong now, needs re-check'), along with the effect ('down-ranked heavily'). This distinguishes it from siblings like mark_superseded, which implies a different semantics (superseded vs. stale).

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

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

It implies when to use (when a memory is probably wrong and needs re-check) but does not explicitly contrast with alternatives like mark_superseded or verify_memory. No 'when not to use' guidance is given, so the agent must infer the boundaries from the phrasing.

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 burden of behavioral disclosure. It indicates the operation is a read (full text retrieval) and lists included fields (confidence score, lifecycle status), but it does not explicitly state that it is read-only or that it does not modify memory. It also omits potential error cases, but for a simple get, this is acceptable.

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

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

The description is a single concise sentence that front-loads the primary action ('Full text of one memory by id') and includes no filler. It efficiently conveys the essential information without unnecessary elaboration.

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 presence of an output schema, the description does not need to explain return values in detail, but it does mention key output components (confidence score, lifecycle status). It covers the essentials for calling the tool, though it could hint that the id must reference an existing memory, which is implicit.

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 entry_id is given meaning beyond the schema: the description explains it is an id and that a unique prefix is acceptable. This adds practical value since the schema only provides the type and title with no description.

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

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

The description uses a specific verb ('get') and resource ('memory') and identifies the retrieval by id, which clearly distinguishes it from search_memory (which likely finds by criteria) and list_recent (which lists recent memories). It also adds the detail that a unique prefix is acceptable, making the purpose unambiguous.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention that search_memory should be used when the id is unknown, or that list_recent is for browsing. The phrase 'by id' implies a direct lookup, but explicit conditions for use are absent.

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 burden of disclosing behavior. It clearly signals a non-destructive read operation ('Read') and specifies what data is returned. It does not detail error handling for invalid user inputs, but for a simple profile fetch the disclosure is adequate and accurate.

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 only two short sentences, leads with the action and default, and includes the most relevant output fields. Every clause earns its place with no redundancy or 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?

The tool is simple: one optional parameter and an output schema already present. The description covers purpose, default behavior, and returned fields. Nothing critical is missing for an agent to call this correctly, given the low complexity and the existing output schema.

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

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

Schema description coverage is 0%, so the description must compensate. It does clarify that the optional 'user' parameter defaults to the caller's own profile, adding meaning to the empty-string default in the schema. However, it does not specify the allowed format of 'user' (e.g., ID, username, email), leaving ambiguity for an agent deciding how to populate it.

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 ('Read') and resource ('member profile'), states the default scope ('yours'), and lists the included fields (role, timezone, git identity, about). It clearly distinguishes this read operation from the sibling set_my_profile, which is the write counterpart.

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

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

It explicitly notes the default behavior ('default: yours'), making it clear when no argument is provided. While it doesn't explicitly say 'when not to use' or name alternatives, the read context and the presence of set_my_profile make the intended usage obvious. It stops short of full exclusion guidance, so a 4 is appropriate.

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. It adds the 'Read-only' trait, which is useful, and lists the data fields returned. It does not mention any latency, authentication, or staleness definition, but for a simple read-only tool this is reasonably transparent, though not rich.

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, focused sentence followed by a two-word behavioral note. It front-loads the key purpose and contains zero filler. Every word contributes to the agent's understanding.

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 zero-parameter, read-only tool with an output schema, the description covers everything needed: what data it returns and that it has no side effects. The output schema presumably details the return structure, so nothing critical is missing given the tool's low 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?

The tool has zero parameters, and the schema shows this. The baseline for no parameters is 4, and since the description correctly implies no inputs are needed, it earns that baseline without needing to explain parameter details.

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

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

The description clearly states the tool reports everyone's current task, progress percentage, blockers, and staleness. It specifies a concrete resource (team status) and the fields shown, but it does not explicitly distinguish itself from sibling tools like team_context, so it stops short of a perfect score.

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: call this to see the team's current status. However, it does not state when to prefer this over siblings like team_context or recent_activity, nor any explicit alternatives or exclusions. The guidance is adequate but not explicit.

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

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

No annotations are provided, so the description must carry the burden of behavioral disclosure. It clearly states the two-step action (blame and memory cross-reference) and the repo scope. It does not explicitly state whether the operation is read-only, what happens if line_end is omitted, or whether it triggers any side effects. Overall, it gives a reasonable behavioral snapshot but not exhaustive detail.

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 single sentence efficiently conveys the core function and purpose, with no filler. The main action and the combined memory-lookup aspect are front-loaded, making it easy for an agent to grasp the tool's essence quickly.

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?

This tool combines two operations (git blame and memory search), and while an output schema exists (not detailed here), the description does not address potential edge cases like invalid file paths, line ranges, or how memory matches are presented. The description is minimal for a tool of this complexity, leaving some operational uncertainty.

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%, meaning the description includes no parameter explanations. The schema provides basic types but leaves ambiguity, such as the default of line_end=0 (likely meaning 'to end of file' but not stated). The description adds zero value to parameter semantics, failing to 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 states a specific verb ('Git blame') and resource ('YOUR code repo'), and clarifies the unique added action of cross-referencing team memories. This clearly distinguishes it from the numerous memory-only sibling tools, which lack the blame component. It directly answers the intended question 'who wrote this and did anyone leave notes about it?', making the purpose unambiguous.

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

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

The description implies usage context (wanting to know authorship and associated memories) but does not explicitly mention when not to use it or mention alternatives. There is no guidance on comparing with potentially similar tools like 'why_code' or 'get_memory'. This leaves an agent to infer applicability rather than being explicitly directed.

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 disclosure burden. It does convey ordering behavior ('most recent') and scoping (others' or filtered by author), but it says nothing about empty-state behavior, errors, or whether the result is a single item versus a list. The presence of an output schema partially offsets the return-format 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?

Two tightly written sentences with zero filler. The core action and scoping are front-loaded, and the usage hint follows immediately. Every word 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 one-optional-parameter tool with an output schema and no nested objects, the description covers purpose, usage timing, and the parameter's effect. Nothing critical is missing for correct invocation; edge-case behavior is the only minor gap, which is acceptable given the low 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 0%, so the description must compensate. It does: 'anyone's, or filter by author' meaningfully explains that the single 'author' parameter narrows results, and that omitting it returns anyone's most recent handoff. This adds real semantic value beyond the bare nullable string field in 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?

Declares a specific verb ('Get') and resource ('most recent handoff document'), clarifying scope via 'anyone's, or filter by author.' It identifies the handoff document as a distinct entity among the many memory tools, which separates it from generic get_memory/search_memory siblings, though it never names them explicitly.

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 an explicit, actionable context: 'Ideal first read when continuing someone's work.' This states when to use the tool clearly. However, it offers no when-not-to guidance and names no alternative tools for cases where the most recent handoff is not what's wanted (e.g., list_recent, search_memory).

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 must carry the behavioral disclosure burden. The description states it lists memories and mentions optional filters and default scope, which indicates a read-only operation without saying so explicitly. It does not mention side effects, ordering details beyond 'newest', or any error conditions. Given the lack of annotations, this is minimum viable transparency but not comprehensive.

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 places the core purpose ('List newest memories') first, followed by optional filters and default behavior. Every word contributes value, and there is no redundancy or 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?

The tool is relatively simple with 3 params and an output schema, so the description doesn't need to explain return values. However, it does not cover the 'limit' parameter semantics or provide any usage guidance relative to siblings. While it captures the essentia, the lack of parameter documentation for one param and missing context on when to use it makes it only minimally complete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the 'kind' filter (by kind) and 'project' (by exact project name), which adds meaning beyond the schema. However, it does not mention the 'limit' parameter at all, leaving its semantics (e.g., maximum number of results, its default) to the schema's type and default. This partial coverage warrants a score of 3.

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 ('List') and a clear resource ('newest memories'), and immediately specifies the optional filters (kind, exact project name) and the default behavior (all projects). This clearly distinguishes it from sibling memory tools like 'search_memory' or 'recall' by focusing on recency rather than search criteria.

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 (when you need the most recent memories) but does not explicitly contrast with alternatives such as 'search_memory' or 'entry_history'. It provides no guidance on when not to use this tool or what distinguishes it from siblings beyond the 'newest' aspect. The usage context is implied rather than stated.

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

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

With no annotations, the description must carry the full transparency burden. It discloses that the record is pushed instantly and visible to teammates' agents, which is useful. However, it does not mention persistence, editability, or any side effects (e.g., overwriting, conflicts), leaving some uncertainty for a write operation.

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

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

Two sentences with no filler. The primary purpose is front-loaded, and the key details are conveyed efficiently. Every clause adds value, and it is neither overwritten nor under-specified.

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 tool is straightforward and the description covers the core context (what to record and its immediate visibility). Although the output schema is present, the description does not mention the return value or any prerequisites. For a logging tool, this is largely sufficient; the minor gaps do not impede correct usage.

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

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

Schema description coverage is 0%, so the description must compensate. It maps four of the six parameters: context (situation), decision (what was decided), rationale (why), and files (which files). It does not explain the 'title' or 'tags' parameters, leaving those to the schema alone. Partial compensation is achieved, but a clearer tie-in to all parameters would improve it.

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 ('Record') and resource ('architecture/tooling decision'), enumerating the key content fields (situation, decision, rationale, affected files). This clearly distinguishes it from siblings like save_note or log_solution, which target different content types.

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 the tool: when an architecture/tooling decision is made. It also hints at the audience (teammates' agents) and that it is pushed instantly. However, it does not explicitly contrast with alternatives or state when NOT to use it, though the narrow scope makes misuse unlikely.

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 of behavioral disclosure. It indicates a write operation ('Record') but does not explain side effects, storage behavior, deduplication, or how the record integrates with other memory tools. It also omits details about the optional tags and files parameters, leaving significant behavioral ambiguity for a mutation 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?

The description is a single, concise sentence that front-loads the core purpose and the key benefit. Every word contributes to understanding the tool's role, with no redundancy or filler. It is appropriately structured and immediately 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?

Despite using a sentence that captures the essence, the description is incomplete for a tool with 5 parameters and no annotations. It fails to explain tags and files, provides no usage guidance against siblings, and lacks behavioral details about the recording process. The presence of an output schema reduces the need to describe return values, but the description still leaves significant gaps in what an agent needs to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies 'problem' and 'fix' (solution) and maps 'raw error output' to error_text, covering the required parameters and one optional. However, tags and files are completely unexplained, leaving the agent to infer their purpose from the schema alone. The description adds some semantic value but does not fully compensate for the coverage 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 clearly states the tool's purpose: recording a problem and its fix to avoid re-debugging. It uses a specific verb ('Record') and identifies the resource ('a problem and its fix'). However, it does not differentiate from sibling tools like save_gotcha, save_pattern, or log_decision, which have overlapping functions. The mention of 'raw error output' hints at error_text but leaves tags and files unmentioned.

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 the tool should be used when a problem is encountered and solved ('so nobody debugs it twice'), but it provides no explicit guidance on when to choose this over alternatives. It also does not state any exclusions or prerequisites, leaving the agent to infer usage context without clear direction.

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 the primary effect (no longer in recall, remains in history) and mentions the optional replacement pointer. However, it does not disclose potential side effects on the entry itself (e.g., status change), any prerequisite like existence of replaced_by_id, or error behavior. It is adequate but not exhaustive for a mutation 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 with no redundancy. The core purpose and the key behavioral effect are front-loaded, and the optional parameter is mentioned concisely. 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?

Given a simple two-parameter tool, an existing output schema (per context signal), and no annotations, the description is sufficient for an agent to understand when and how to invoke it. It covers the key effect and the optional parameter. It could mention edge cases (e.g., calling on already superseded entries) but that's minor given the 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?

Schema has zero description coverage, so the description must explain parameters. It clarifies that the tool optionally points to a newer replacement id, which maps to replaced_by_id. The entry_id role is implicit as the target memory. This adds meaning beyond the bare parameter names, though it doesn't specify formats or constraints (e.g., whether replaced_by_id must exist).

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 ('Mark') and resource ('an outdated memory') with a clear outcome ('superseded'), and distinctively notes that it stops appearing in recall but stays in history. This distinguishes it from similar memory mutation tools like delete_memory or flag_stale without needing to inspect 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?

The description implies when to use it (when a memory is outdated and being replaced) but does not explicitly contrast it with alternatives like delete_memory or flag_stale. It gives the effect (stops appearing in recall, stays in history) which helps an agent infer context, but there is no explicit 'use this instead of' 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 of behavioral disclosure. It conveys that this is a read operation and that ref selects a point in time, but says nothing about how kind filters results, how limit truncates, ordering behavior, or what happens when a ref does not exist. The core behavior is clear but the operational detail is thin.

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 with no waste. The core concept ('Time travel') is front-loaded, the mechanism ('AS OF a specific commit SHA, tag or branch') follows immediately, and the usage hint closes it out. Every word 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?

Despite the presence of an output schema covering return values, the definition leaves two of three parameters (kind, limit) unexplained, and misses edge-case behavior for invalid or empty refs. For a moderately complex time-travel tool with filtering and limiting controls, this is a meaningful completeness gap.

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 for all three parameters. It effectively explains 'ref' by naming the accepted value types (commit SHA, tag, branch), but 'kind' and 'limit' receive zero explanation in the description and their semantics are not guessable from the schema beyond their names. One of three parameters documented is insufficient compensation.

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 ('read') and resource ('crew memory AS OF a specific commit SHA, tag or branch'), pairing it with an evocative 'time travel' metaphor that immediately distinguishes it from current-state siblings like recall, list_recent, and search_memory. An agent can clearly tell this reads historical memory at a point in time.

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 'Great for "what did we know back then"' line gives a clear triggering scenario for when an agent should reach for this tool. It does not explicitly name alternatives or state when not to use it, but the historical-versus-current framing strongly implies the boundary against list_recent and get_memory.

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 says 'Automatic index' which implies a read-only aggregation, but it does not explicitly state that it makes no changes to memory, nor does it disclose any potential side effects or performance implications. The description hints at passivity but fails to clearly disclose the non-destructive nature.

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

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

The description is a single, compact sentence that conveys the tool's core function without any fluff. It front-loads the primary purpose ('Automatic index of everything in memory') and lists the grouping dimensions efficiently. Every word 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 that the tool has no parameters and an output schema exists, the description covers the essential information: what it does (counts by various dimensions) and its scope (everything in memory). It does not describe the output format, but the presence of an output schema mitigates that need. The description is sufficient for an agent to understand when and why to invoke it.

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 the schema coverage is 100% (no properties). The description does not need to explain parameters, and the baseline for 0 parameters is 4. No additional parameter detail is required.

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

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

The description clearly states the tool's purpose: providing counts of memory items grouped by type, author, lifecycle status, project, and top tags. This is a specific verb (index/count) and resource (memory), and it differentiates from siblings like search_memory (search) and list_recent (list) by focusing on aggregated statistics over everything in memory.

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

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

The description implies this is for getting an overview of memory contents, but it does not explicitly state when to use it over alternatives like list_recent or search_memory. There is no mention of 'use when you need a high-level summary' or exclusions, leaving the usage context somewhat implicit.

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. It uses 'finds' and 'flags', which imply a read/analysis operation without side effects, and adds context that it enables the AI to supersede/update memories later. It does not explicitly state that the tool itself never mutates memory, but the wording strongly suggests it is diagnostic. This is adequate but not fully explicit, so a 4 is appropriate.

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 with no wasted words. It front-loads the purpose and effectively conveys both the action and the intended outcome. Every clause contributes to understanding.

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 core behavior and context (current branch diff, base_ref, memory filtering). Since an output schema exists, return values don't need explanation. It could optionally note that it does not modify memories, but that is implied. Overall, it's nearly complete for an agent to decide whether to call it.

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

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

The only parameter, base_ref, is referenced in the description as the comparison base for the diff, giving it functional meaning beyond the schema (which has no description and a default of 'main'). This compensates for the 0% schema coverage, making the parameter's role clear. However, it doesn't explain format or allowed values, which is minor given the default.

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

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

The description clearly states the tool's function: reviewing the current branch diff against a base_ref, and then finding memories touching changed files and flagging those likely obsolete. It uses specific verbs ('Review', 'finds', 'flags') and distinguishes itself from sibling tools like search_memory or log_decision by focusing on PR context. An agent can immediately grasp what it does and why it is unique.

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 (use when you want to review a diff for memory obsolescence) but does not explicitly state when to prefer this over alternatives, nor does it mention exclusions or when not to use it. It lacks direct comparison to siblings like recall or search_memory, so the agent must infer the appropriate 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 carries the burden. It mentions 'ranked by relevance x recency x confidence' and 'packed into a context budget,' hinting at output truncation and ranking behavior. It implies a read-only operation but does not explicitly state that it does not modify memory. It lacks details on rate limits, authorization, or what happens when the budget is exceeded. This is adequate but not rich.

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 sentences, no filler. The first sentence front-loads the core functionality and ranking scheme; the second adds a usage preference. Every word earns its place, making it easy for an agent to parse quickly.

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 tool's essence and a usage preference, and the output schema handles return values. However, it omits any guidance on query syntax, budget_chars limits, or how scope defaults behave beyond the default value in the schema. For a 3-parameter tool with zero schema coverage, this is a moderate gap — the agent can likely call it correctly, but may not optimize parameter choices without more detail.

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 explain parameters. It mentions the scope parameter with its possible values ('team'|'personal'|'all'), which is helpful. However, it does not explain the query parameter (e.g., free text, exact match) or the budget_chars parameter beyond the vague 'context budget.' Since two of three parameters are effectively undocumented, the description fails to compensate for the schema 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 clearly states a specific action: 'keyword search ranked by relevance x recency x confidence, packed into a context budget.' It also specifies the resources searched (team and personal memory) and explicitly contrasts with 'raw search,' distinguishing it from the sibling tool search_memory. This gives an agent a precise understanding of what the 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?

It provides a clear usage condition: 'Prefer this over raw search when answering questions.' This tells the agent when to choose this tool over a generic alternative. However, it does not mention other siblings like list_recent or team_context, nor does it specify when not to use it (e.g., for exact matches, use something else). So it has one clear guidance but lacks comprehensive 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 provided, the description carries the full burden of behavioral disclosure. It mentions the types of activity and ordering (newest first) but does not disclose whether the operation is read-only, if it has side effects, pagination behavior, rate limits, or what happens when the 'author' is null (presumably returns all). The description is too sparse for a tool with no annotation safety profile.

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 core purpose and includes examples of activity types and ordering. It is concise with no filler, making it easy to parse. A minor deduction for not mentioning the limit parameter, but overall it is efficient.

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

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

Given an output schema exists, return values need not be described. The description covers the main aspects: what activity is shown, ordering, and filtering. However, it omits clarification on the scope of 'crew memory activity' (what is a crew?) and does not explicitly state that 'limit' caps results. The tool is simple, but the description leaves some gaps that an agent would need to resolve.

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 explain both parameters. It only references 'per author' for the 'author' parameter, but says nothing about 'limit' (except the schema default of 30). The meaning of 'limit' as a maximum number of entries is not stated, and the description fails to fully compensate for the missing schema documentation.

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

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

The description clearly states what the tool does: it returns a timeline of crew memory activity (statuses, saves, lifecycle changes) newest first, with optional per-author filtering. This is a specific verb+resource with concrete attributes, though it does not differentiate from sibling tools like 'list_recent' which may be similar. Still, the purpose is unambiguous.

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

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

The description gives no indication of when to use this tool versus alternatives. It does not mention any exclusions, alternative tools, or specific scenarios that call for this tool. The omission of any comparison to 'list_recent' or other memory-related tools leaves an agent without routing 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 must carry the burden of behavioral disclosure. It uses 'Get' implying a read-only operation, and the note that 'The AI writes the actual summary' indicates the tool does not itself write to memory. However, it does not mention potential errors (e.g., invalid refs), authentication requirements, or any side effects. This is adequate but not rich.

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, dense sentence that front-loads the core purpose ('Get a formatted commit log + changed-files summary of base..head') and then adds usage context. Every phrase earns its place, with no fluff. It is appropriately concise and well-structured.

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 there is an output schema (context signals say 'Has output schema: true'), the description need not explain return values. It covers the tool's purpose, the expected usage context (to feed into save_note/log_decision), and the source ('YOUR CODE repo'). However, it lacks details about what happens with invalid refs or any prerequisites, leaving a small gap. Overall, it is fairly complete for a read-only tool, just not exhaustive.

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 'base..head' which hints at the parameters, but does not explain that base_ref is required or that head_ref defaults to HEAD. The meaning of base/head is not explicitly defined, leaving some ambiguity for an agent. The description provides minimal added value beyond the parameter names themselves.

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 gets a formatted commit log + changed-files summary of base..head from the code repo. It names the specific resource and action, and distinguishes itself from siblings like save_note/log_decision by noting the output is 'ready to summarize' into those tools. It is not a tautology and explains the tool's purpose precisely.

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 clear context: it is used to fetch commit data that will be summarized into a note or decision with save_note/log_decision. It implies when to use it (before those tools) but does not explicitly state when not to use it or name alternatives like git_blame_context. The 'from YOUR CODE repo' adds specificity. Overall, it provides clear context but lacks explicit exclusions.

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. It states the action ('save') which implies a write operation, but it does not disclose any side effects, such as whether the gotcha is stored permanently, whether it can be overwritten, how it will be retrieved, or whether it affects existing memories. The description adds little beyond the verb itself.

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, punchy sentence that immediately conveys purpose and content style. It contains no filler and is front-loaded with the core action and examples.

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 tool has 4 parameters (1 required), no annotations, and an output schema that is not described. The description gives only the gotcha content pattern and omits usage context, parameter semantics, and expected outcomes. For a 4-parameter tool, this is insufficient for an agent to call it correctly without inspecting the schema.

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

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

Schema description coverage is 0%, so the description must explain the parameters. It only illustrates the content of the 'gotcha' field ('X breaks when Y') but gives no meaning for 'tags', 'files', or 'details'. Without that, an agent cannot know what values to provide or why they exist.

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: saving a small trap that cost time, with concrete examples ('X breaks when Y', 'always Z before W'). It uses a specific verb ('save') and resource ('gotcha'), and the examples differentiate it from siblings like save_note or save_pattern by focusing on costly pitfalls.

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 (for small traps that cost time) and suggests conciseness ('Short and punchy'), but it does not explicitly name alternative tools or state when NOT to use it. Sibling tools like save_note, save_pattern, and save_handoff exist, but no comparative guidance is provided, leaving some ambiguity.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Write a session handoff,' which implies mutation but does not disclose whether it creates a new entry, overwrites the latest handoff, or how it interacts with siblings like latest_handoff. It also omits any consequences (e.g., persistence, idempotency) or return behavior. The description provides minimal behavioral context beyond the verb.

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

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

The description is two concise sentences with no wasted words. It front-loads the verb and resource, then immediately enumerates the content fields and the purpose. Every sentence earns its place; there is no fluff or repetition.

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 write tool with four parameters and no annotations, the description covers the core intent but lacks details such as idempotency (does it overwrite the latest handoff?), session scoping, and any preconditions. The output schema likely covers return values, but the description alone does not address edge cases like repeated calls. It is sufficient for a straightforward usage but not exhaustive.

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 maps each parameter to its meaning: summary='what was done', next_steps='exact next steps', blockers='current blockers', open_questions='open questions'. This gives agents a clear semantic for the required parameters and optional fields, adding substantial value beyond the raw schema.

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

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

States a specific verb ('Write') and resource ('session handoff') and enumerates the content: what was done, exact next steps, blockers, open questions. This clearly distinguishes it from siblings like save_note (general notes) and log_decision (decisions), even though no alternatives are named.

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

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

Implies usage context by stating 'The next session or teammate starts from this instead of zero,' suggesting it should be used when ending a session to provide continuity. However, it does not explicitly contrast with related write tools like save_note or log_decision, nor mention when not to use it. The guidance is implied rather than explicit.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that saving pushes instantly, that files links repo paths for PR review and decay tracking, that scope 'personal' ensures privacy on the local machine, and that secrets should never be stored. This adds meaningful context beyond the schema, though it does not mention any authentication, rate limits, or side effects beyond the push.

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?

Three sentences with no redundancy. The core purpose is front-loaded, followed by essential parameter clarifications and a safety warning. Every sentence earns its place; nothing is wasted.

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 existence of an output schema (which should cover return values) and the relative simplicity of the tool, the description covers the essential behavioral and parameter context. It might mention error handling or retention expectations, but these are likely covered by the output schema or are not critical for a save operation. The warning about secrets is a valuable addition.

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 the description must compensate. It explains the semantics of the two most ambiguous parameters: files (links repo paths, enables PR review + decay tracking) and scope ('personal' keeps private on this machine). Title and content are self-evident from the tool's purpose, but tags are not explained. Still, the description provides enough to understand the non-obvious parameters.

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: saving durable knowledge (conventions, environment quirks, how-to) to shared memory, with immediate pushing. This is a specific verb+resource combination that distinguishes it from the many specialized save tools (save_gotcha, save_pattern, save_handoff) by its general scope, though it doesn't explicitly name those 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 implies usage through examples of what to save (conventions, quirks, how-to) and what not to save (secrets), giving contextual guidance. However, it does not explicitly state when to use this tool versus the specialized siblings, nor does it mention any conditions under which this tool should not be used beyond the secret prohibition.

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 must disclose behavioral traits. It only states 'Save' with no mention of persistence, overwriting behavior, access requirements, or side effects. Insufficient for a mutation 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?

A single, concise sentence with a clear example. Front-loaded with the core purpose. Efficient but slightly abrupt given the tool's parameter complexity.

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 5 parameters, no annotations, and no parameter descriptions in the schema, this description is too thin. It does not explain the purpose of optional fields or the expected outcome, leaving an agent to guess.

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 explain parameter meanings. It does not elaborate on pattern_name, description, tags, files, or example. The description adds no parameter context beyond the schema's property titles.

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 (save) and resource (recurring codebase/project pattern) with examples. Clearly differentiates from general note/decision tools in intent, though it does not explicitly name sibling 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?

Provides no guidance on when to use this tool versus siblings like save_note, log_decision, or save_gotcha. No conditions, exclusions, or alternative references – the usage context is only implied by the word 'pattern'.

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 communicates that the search is 'raw', implying no ranking, and explains the empty-query behavior. It does not explicitly state read-only status or side effects, but the 'search' action implies a non-destructive operation. This is adequate but not exhaustive.

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

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

Two sentences, front-loaded with the core purpose, then the filter list, then the alternative. Every sentence earns its place with zero fluff. The structure is ideal for quick parsing.

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?

An output schema is present, so return-value details are not needed. The description covers all essential usage points: the operation type, filter dimensions, empty-query semantics, and the routing to recall for ranking. For a search tool with seven parameters, this is complete.

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

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

Schema description coverage is 0%, so the description must compensate. It lists all filter parameters and adds critical meaning: 'kind' values are enumerated, 'file' is defined as a 'path substring', and the empty-query behavior is explained. It does not mention the 'limit' parameter or tag array format, but overall it provides substantial semantic value 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 performs a 'raw faceted search across crew memory', specifying a concrete verb and resource. It explicitly names the filter dimensions (kind, tags, author, file, project) and distinguishes itself from the sibling 'recall' by noting that recall provides 'smart ranking instead'.

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 versus the alternative by stating 'Use recall() for smart ranking instead'. It also defines behavior for an empty query ('Empty query with filters lists matches'), giving clear context for invocation.

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 behavioral disclosure burden. It does disclose that this is an upsert ('Create/update') and adds a useful behavioral trait: 'Git identity is auto-included when available'. However, it does not state whether omitted fields are reset/cleared, whether the operation merges with existing values, or any permissions/ownership checks implied by 'YOUR profile'. This is acceptable for a simple self-profile setter but leaves ambiguity about overwrite semantics.

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?

A single sentence that front-loads the core purpose and packs the field list and an extra behavioral note without waste. Nothing is redundant with the schema titles, and every clause 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 the low complexity (three optional string fields), the description is nearly sufficient, and the existence of an output schema covers return values. The main gaps are merge/reset semantics and timezone format, which an agent might need to avoid unintended field clearing. The 'Git identity' note adds useful context, but the description does not fully close the behavior gap for a mutating tool with no annotations.

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

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

The schema provides only titles with no descriptions (0% coverage), so the description must compensate. It does map two parameters explicitly ('role like backend dev', 'timezone') and clarifies 'about' as 'free-text about'. The role example adds some value beyond the bare title, but timezone format and empty-string behavior are not addressed. This is partial compensation for the schema 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 uses a specific verb ('Create/update') and resource ('YOUR member profile'), and clarifies that it targets only the caller's profile, which distinguishes it from sibling read tools like get_profile and memory-oriented tools. The parenthetical lists exactly which fields are touched, so an agent can tell what the tool is for without opening the 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?

The description implies this is for the caller's own profile and could be used to set role, timezone, and about text. However, it gives no explicit guidance on when to prefer this over alternatives such as get_profile or update_status, and it does not state whether this tool is meant for initial setup or ongoing edits. It reads as a 'use this to modify your profile' without exclusions or comparison to siblings.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that sync is manual and that offline writes are queued and pushed, which is helpful. However, it does not explain what happens on pull (e.g., overwrite vs merge), how conflicts are handled, or any side effects, leaving a notable gap for a sync operation.

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

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

The description is two concise sentences. The first sentence front-loads the purpose and parameter format, and the second provides usage context. Every word contributes to understanding, with no redundancy or 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?

For a single-parameter tool with an output schema, the description covers the essentials: what it does, when to use it, and the parameter meaning. It doesn't mention prerequisites like GitHub authentication or conflict resolution, but given the tool's simplicity and the presence of an output schema, it's sufficiently complete for correct 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?

The schema only defines 'direction' as a string with a default and no description. The description adds meaning by enumerating allowed values ('pull|push|both') and implying their effects through the offline-write context. This compensates for the 0% schema coverage, though it doesn't elaborate on each direction's exact 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?

The description clearly states the tool's function: 'Manual sync with GitHub', and specifies the direction parameter values. This distinguishes it from sibling tools like recall or search_memory, which are about retrieval. However, it doesn't explicitly contrast with a specific alternative, so it stops short of a perfect score.

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

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

It provides a concrete use context: 'Useful after working offline' and explains that offline writes are queued locally and pushed. This gives clear guidance on when to invoke the tool. It doesn't mention alternatives for cases where sync isn't needed, but the context is sufficiently explicit.

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

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It adds context about 'project and branch attribution stay correct across projects,' implying this tool establishes or maintains attribution. However, it does not state whether the tool is read-only or mutates state, what kind of briefing it returns, or any side effects beyond attribution. This is a partial 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?

The description is two sentences long with zero filler. The core purpose is front-loaded, followed by parameter guidance and usage timing. Every word 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?

The tool is simple (one parameter) and has an output schema, so the return value is already documented. The description covers purpose, when to call, and the parameter's meaning. The only gap is explicit disclosure of whether the tool modifies state (e.g., sets context) beyond the briefing, which would be useful but is not critical given the output schema and clear 'briefing' wording.

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 0% description coverage, so the description must compensate. It explains project_path: 'Pass the absolute workspace/repo root in project_path' and notes why it matters ('so project and branch attribution stay correct'). This gives meaningful semantic guidance. However, it does not clarify what happens if the parameter is omitted (schema shows it's optional with a default), leaving that ambiguity.

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 as a 'Session-start briefing for the current project.' The verb 'briefing' and resource 'current project' specify exactly what it does. It distinguishes itself from sibling memory tools by its timing ('at every session start') and its role as a briefing, which none of the other siblings (like recall, search_memory, or get_team_status) claim.

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 timing: 'Call this FIRST at every session start.' This tells the agent exactly when to invoke it. It does not mention alternatives or exclusions, but the instruction to call it first makes its usage context clear. Since no sibling appears to be a session-start briefing, explicit alternative routing isn't critical.

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 must carry the full burden of behavioral disclosure. It does state that 'Teammates see it instantly,' which is a useful behavioral trait. However, it does not explain whether this overwrites the previous status, how the status is stored, or any side effects (e.g., persistence). It is not misleading but lacks depth on the tool's internal behavior.

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

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

The description is two sentences with zero waste. The purpose and parameters are in the first sentence, and usage timing and effect in the second. It is front-loaded and every phrase 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 the primary purpose, parameters, usage timing, and audience. It includes an output schema (though not shown here) so return values need not be explained. It does not cover edge cases like required permissions or rate limits, but for a simple status-update tool, the context provided is adequate. A 4 reflects that it is mostly complete but could mention persistence or side effects.

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 explain the parameters. It mentions 'task description, optional progress percent, optional blockers list,' which maps to the three parameters. However, it does not specify the range of progress (e.g., 0-100), the format of blockers (list of strings), or what happens when fields are omitted. Given that the schema provides no descriptions, this is a notable deficiency.

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 'Announce' and a clear resource (the agent's current work status) for the whole team. It explicitly lists the fields (task, progress, blockers), which clearly distinguishes it from sibling tools like get_team_status or set_my_profile. There is no ambiguity about 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?

The description explicitly states when to call it: 'at session start and whenever the task changes.' It also conveys that it broadcasts to the team. However, it does not mention alternatives or when not to use it, which would have been a 5. The guidance is clear and actionable for an agent.

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 of behavioral disclosure. It discloses concrete effects: verified memories 'rank higher and decay slower.' This is useful behavioral context beyond the basic action, but it does not mention other side effects (e.g., timestamp updates, permission requirements) or clarify the scope of 'decay slower.' For a simple action, this is adequate but not exhaustive.

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, tightly constructed sentence that front-loads the action and immediately explains the meaning of 'verified' plus the behavioral consequence. There is zero waste; every clause 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 single-parameter tool with an output schema, the description covers the essential semantic: what the action does and its effect. It does not mention possible failure conditions or tie-ins to other tools, but for a simple marking operation, this is reasonably complete. The output schema handles return-value specifics, so its absence is not a gap.

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 for missing parameter documentation. The only parameter, entry_id, is untouched by the description—there is no indication of its format, how to obtain it, or any constraints. The parameter name is self-explanatory, but the description adds no value beyond the schema, failing to compensate for the coverage 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 states a specific verb ('mark') and a specific resource ('a memory'), with a clear clarification of what 'verified' means ('you checked it is still true'). It also distinguishes the tool from related sibling operations like flag_stale or mark_superseded by describing the behavioral outcome (higher ranking, slower decay). This is sufficient for an agent to identify its purpose uniquely.

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 does not provide explicit usage guidance relative to alternatives. It only implies the action taken after verifying a memory's truth, but does not state when to use this instead of flag_stale, mark_superseded, or other memory-management tools. No exclusions or comparisons are provided.

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 that answers come from crew memory and are ranked, indicating a read-only lookup. However, it does not mention behavior on no matches, ranking criteria, or scope limitations. The basic transparency is there, but at a minimum level for a lookup 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?

The description is two sentences, front-loads the core question in quotes, and immediately states the sources and ordering. Every word contributes; no filler or redundancy.

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

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

For a tool with one parameter and an output schema, the description covers the purpose, data source, and ranking behavior. Minor gaps include handling of empty results and explicit note that it is read-only, but these are not critical given the schema and 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?

With only one parameter and 0% schema coverage, the description must explain 'target'. It implies target is the path or code reference being questioned, but the exact format (e.g., full path, partial, regex) is unspecified. It adds some meaning beyond the bare schema, but not enough to fully compensate for the coverage 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 a specific verb ('Lookup') and resource ('decisions/solutions/gotchas/patterns linked to a path'), and directly answers the tool's namesake question 'Why does this code/file exist?'. It clearly distinguishes from generic memory tools like search_memory by focusing on rationale and the 'why', not merely retrieving facts.

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 the tool is for understanding the rationale behind code, but it does not explicitly compare to alternative tools such as recall or search_memory, nor does it state when not to use it. The context is clear but exclusions and alternative routing are absent.

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