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

No annotations are provided, so the description bears full burden. It states it searches principles file and semantic history, but does not disclose if the tool is read-only, what permissions are needed, or the format of the output.

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 very concise with two sentences, no wasted words. It is front-loaded with the core action. However, it might be too brief for some details.

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 simple tool with one parameter and no annotations, the description provides basic context. An output schema exists (not shown) which likely documents return values, so the description is adequate but not thorough.

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 input schema has one parameter 'decision' with no description, and schema description coverage is 0%. The description does not elaborate on what constitutes a valid 'decision' or provide examples, leaving the agent to infer meaning from the parameter name alone.

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

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

The description clearly states the tool's purpose: checking alignment of a decision with principles. It distinguishes from sibling tools like list_principles or get_principle by focusing on alignment rather than retrieval.

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

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

The description implies usage for alignment checks but does not explicitly state when to use this tool versus alternatives like list_principles or get_principle. No guidance on when not to use it.

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

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

With no annotations, the description carries full transparency burden. It discloses the outputs for each view (e.g., 'domain breakdown with counts, %, breakthroughs, top concepts') but does not explicitly state side effects or safety guarantees (likely read-only). The behavioral traits are well described but lack explicit non-destructive confirmation.

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

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

The description is well-structured with a summary line followed by a detailed Args block. While slightly verbose, every sentence adds value. It could be trimmed slightly without losing information.

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

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

Given the single parameter and presence of an output schema, the description covers the main views adequately. However, it lacks details on return value structure or interpretation of the 'pulse' matrix, which might be needed for full completeness.

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% coverage (no parameter descriptions), so the description fully compensates. It provides detailed explanations for each 'view' value, including defaults and what each displays, adding significant meaning beyond the schema.

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

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

The description clearly states that the tool provides 'Brain overview, domain distribution, and thinking pulse' and enumerates specific views (overview, domains, pulse, etc.) with distinct purposes. This differentiates it from sibling tools like 'cognitive_patterns' or 'query_analytics'.

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 lists available views but does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention when not to use it. Usage is implied by the view descriptions.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It only states it analyzes and answers a question, but does not disclose whether it is read-only, destructive, requires authentication, or any side effects. This is insufficient for an agent to safely invoke the tool.

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

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

The description is very concise (two sentences) and front-loaded with the main purpose. However, the second sentence is somewhat vague ('with data') and could be more informative without being substantially longer.

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 an output schema exists (but is not visible), the description does not need to detail return values, but it still fails to explain the parameter's role or provide enough context for the agent to use the tool effectively. The description is too sparse for a tool with no annotations and minimal schema info.

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 input schema has one parameter 'domain' with no description (0% schema description coverage). The description does not mention this parameter at all, providing no additional meaning or guidance on its purpose, valid values, or effect. The schema coverage is minimal and the description fails to compensate.

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 analyzes cognitive patterns and problem-solving approaches, answering a specific question ('When do I think best?'). This provides a clear verb and resource, but it does not explicitly distinguish itself from siblings like brain_stats or what_do_i_think, so it misses a top 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 when one wants to analyze cognitive patterns or determine optimal thinking times, but it offers no explicit guidance on when to use this tool versus alternatives, no when-not-to conditions, and no contextual cues for 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?

Discloses it returns recent summaries and accumulated state. Lacks details on auth needs, rate limits, or any side effects. No annotations provided, so description carries burden but is 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?

Three sentences, front-loaded with purpose. The line about 'prosthetic's core value' is somewhat poetic but adds minimal clarity; overall concise and to the point.

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

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

Despite having an output schema, the description omits parameter semantics and any indication of output structure beyond 'recent summaries + accumulated state'. Incomplete for effective agent use.

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

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

Input schema has 2 parameters (domain, summary_count) with 0% description coverage. Description does not explain what domain represents or how summary_count affects results, leaving the agent with no guidance.

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

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

Clearly states it returns a 'waking up' brief for re-entering a domain, including recent summaries and accumulated state. Distinguishes from siblings like get_conversation or search_summaries by focusing on full context recovery.

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 when re-entering a domain, stating 'making re-entry cheap'. No explicit when-not-to-use or alternative tools mentioned among the many 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?

No annotations are provided, so the description must convey behavioral traits. It only states it retrieves conversations by date, omitting key details like read-only nature, pagination (via limit), or scope. This is insufficient for safe invocation.

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

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

The description is concise (one sentence) but under-specifies. It could be expanded with key details (e.g., return format) without becoming verbose.

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

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

Without annotations and param descriptions, the description is too minimal. The output schema exists but is not leveraged. The tool's behavior (e.g., scope, sorting) is unclear, leaving gaps for an AI agent.

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

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

With 0% schema description coverage, the description should elaborate on parameters. It only mentions the date format. The 'limit' parameter's purpose is implied but not explicitly described, and no default behavior is explained. This adds negligible value over the schema.

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

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

The description clearly states the action ('Get conversations') and the filter ('specific date'), with the date format specified. It distinguishes from siblings like 'search_conversations' and 'get_conversation' by focusing on date-based retrieval.

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

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

The description implies usage when a specific date is known but provides no guidance on when to avoid this tool or alternatives. No comparisons to sibling tools are made.

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

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

No annotations provided, so description carries full burden. It hints at a read-only check ('forgotten') but does not disclose side effects, permissions, or behavior like filtering or consequence.

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 short, front-loaded sentences with no wasted words. Each sentence 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?

Despite having output schema, the description lacks critical details: definition of 'tunnels', parameter roles, output structure, or comparison to siblings. Minimal for a tool with two parameters.

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

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

Schema description coverage is 0%. Description mentions no parameters (min_importance, limit), leaving their meaning and impact completely unexplained.

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 specifies 'find abandoned tunnels' with a clear metaphor 'domains with open questions you haven't resolved.' It distinguishes from siblings like 'open_threads' and 'tunnel_state' by emphasizing unresolved questions, but the term 'tunnels' is not defined.

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

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

The phrase 'what have I forgotten?' alarm provides context for when to use (forgotten topics), but no explicit when-not or alternatives. It implies usage but lacks 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?

No annotations are provided, so the description bears the full burden of behavioral disclosure. It does not mention whether the tool is read-only, requires permissions, or has any side effects, leaving significant gaps.

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 consists of two concise sentences, each serving a distinct purpose: stating the tool's function and providing usage guidance. No unnecessary words.

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

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

Given the tool's simplicity (single required parameter, output schema exists), the description covers the essential purpose and prerequisite. It is complete enough, though additional behavioral context would be beneficial.

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

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

Schema description coverage is 0%, so the description should compensate by explaining the parameter. However, it only says 'by ID' without adding details about format, constraints, or expected values for conversation_id.

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 'Get the full content of a specific conversation by ID,' using a specific verb and resource. It also distinguishes from the sibling tool search_conversations by implying that search outputs IDs, while this tool retrieves full content.

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 advises to 'Use search_conversations() first to find conversation IDs,' providing clear guidance on when to use this tool compared to alternatives.

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

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

No annotations exist, so description must disclose behavior. It only states 'get detailed info', but does not mention what happens if principle not found, whether it's read-only, or any side effects.

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 sentence, which is concise but borders on overly terse. It lacks any structure or 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 1 parameter and an output schema, the description is still insufficient. It doesn't explain what 'detailed info' entails or how to use the tool effectively.

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

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

The sole parameter 'name' has no description in the input schema (0% coverage) and the description adds no additional meaning, format hints, or constraints.

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 action ('Get') and resource ('principle'), and distinguishes from 'list_principles' (which would list multiple). It implies returning detailed info for a single principle.

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

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

No guidance on when to use this tool vs siblings (e.g., when you need details vs a list). No prerequisites or contextual use cases 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 must disclose all behavioral traits. It explains the search functionality and modes but does not mention whether the tool is read-only, requires authentication, has rate limits, or any side effects. It is adequate but lacks safety/permission details.

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

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

The description is concise and front-loaded with the overall purpose. It then breaks down modes and parameters efficiently. Minor redundancy exists with the opening sentence being somewhat repeated in the mode list, but overall every sentence adds value.

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

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

Given the tool's complexity (multiple modes, 4 parameters, no annotations) and the existence of an output schema, the description is quite complete. It covers all parameters and mode behaviors. It does not explain output format or edge cases, but the output schema fills that gap. Slightly more detail on scaling or error conditions would improve, but it's sufficient.

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

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

The schema has 0% description coverage, so the description fully compensates by explaining each parameter's role. It details how 'query' is used for code search or as conversation_id, 'project' for timeline/conversations, 'mode' with four clear options, and 'limit' as max results. This adds significant meaning beyond the raw JSON 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 searches GitHub repos, commits, and cross-references with conversations. It lists specific modes (timeline, conversations, code, validate), which differentiates it from sibling tools like 'search_conversations' or 'unified_search' that focus only on conversation data.

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

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

The description gives explicit guidance for each mode, including how to pass parameters (e.g., 'Pass conversation_id as query' for validate mode). However, it does not directly compare to sibling tools or state when not to use this tool, leaving some ambiguity about alternatives.

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

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

Given no annotations, the description explains the read-only operation and data source. It does not disclose potential error states or authentication needs, but the behavior is adequately transparent for a simple list 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 extremely concise with two sentences, front-loading the action and adding relevant context. Every sentence serves a purpose.

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, no parameters, and presence of an output schema, the description is complete. It clarifies the source of principles, leaving no ambiguity for agent 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 tool has no parameters, so baseline is 4. The description adds no parameter info, but none is needed since the schema already covers the empty parameter set.

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

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

The description clearly states the tool lists configured principles and specifies the source from a YAML/JSON file, effectively distinguishing it from 'get_principle' which likely retrieves a single principle.

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

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

The description implies usage for listing all principles but does not explicitly mention when to use it versus alternatives like 'get_principle'. No exclusions or prerequisites are 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?

No annotations provided. The description only says it is an inventory/dashboard but does not disclose side effects, authentication needs, rate limits, or return format. With no annotations, the description carries the full burden and fails to convey behavioral traits.

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

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

Two concise sentences with clear metaphor. Every word earns its place. No redundancy or unnecessary detail.

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 an output schema existing, the description is too brief for a tool with two parameters and no schema descriptions. It omits crucial context about what 'open questions' means, how pagination or domain aggregation works, and how it differs from very similar sibling tools like 'unfinished_threads'.

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% and the description does not mention the two parameters (limit_per_domain, max_domains) or their meaning. The agent gets no help understanding how to use these parameters to control the query.

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 that the tool retrieves a global inventory of all open questions across all domains, using 'unfinished business' dashboard metaphor. However, it does not differentiate from the sibling tool 'unfinished_threads', which may cause confusion about scope.

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

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

No explicit guidance on when to use this tool vs alternatives like 'unfinished_threads', 'dormant_contexts', or 'search_conversations'. The description implies it's for a high-level overview but lacks when-not-to-use or prerequisites.

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

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

No annotations provided, so the description must fully disclose behavior. It describes what the tool does but does not state it is read-only, whether it modifies data, requires authentication, or has rate limits. The agent lacks insight into side effects or safety.

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 structured as a docstring with a clean arg list. It is relatively concise and front-loaded with the main purpose. Minor redundancy could be trimmed (e.g., repeating 'YYYY-MM-DD format' is fine).

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 5 parameters and an output schema (unknown content). The description covers input behavior well, but omits behavioral details (read-only, pagination, error handling) and does not mention what the output schema provides. It is adequate but not fully complete.

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

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

With 0% schema description coverage, the description adds substantial meaning to all 5 parameters: view's options and descriptions, date format, month format, source examples, and limit default. This fully compensates for 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 queries analytics across specific views (timeline, stacks, problems, spend, summary), with a specific verb 'query' and resource 'analytics'. It distinguishes itself from sibling tools that focus on conversations, searches, and other areas.

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 use cases for each view (e.g., 'What happened on a specific date' for timeline), but does not explain when to use this tool over siblings or when not to use it. No alternatives or exclusions are mentioned.

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

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

Describes search behavior and special logic for empty term with role. However, lacks any mention of read-only nature, response structure, or performance characteristics, which is notable given no annotations.

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

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

Concise description with a clear one-line summary followed by parameter details. Could streamline by merging but overall efficient.

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

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

Covers all parameters with special logic, and with output schema provided, needs no return description. However, lacks hint about search matching (fuzzy/exact) or performance, which could affect agent's decision to use it in time-sensitive contexts.

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, but the tool description fully explains all three parameters including default values, special behavior, and role filtering logic. This is exceptional value beyond the schema.

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

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

Clearly states it performs full-text search across conversation messages, distinguishing it from search over documents or summaries. However, it does not explicitly contrast with sibling tools like semantic_search or unified_search.

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

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

Provides usage context for empty term and role filtering but lacks explicit when-to-use and when-not-to-use guidance compared to sibling tools like semantic_search or unified_search.

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 explains the behavioral differences between keyword and semantic search per filter, and discloses the default behavior. It does not cover side effects or auth needs, which are minimal for a read-only search 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 multi-line docstring with an Args section, which is reasonably concise but could be more streamlined for JSON. It is front-loaded with the main purpose, but the format uses Python-style notation that may be less familiar in some contexts.

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 optional parameters, an output schema, and a comprehensive description covering all parameters and behavioral nuances, the tool definition is complete. No critical gaps are present.

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. The docstring provides detailed explanations for each parameter, including filter options, project usage, limit, and min_depth, adding significant meaning beyond the schema titles and defaults.

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

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

The description clearly states the tool searches markdown corpus and IP documents with various filters, specifying the verb 'search' and the resource. It distinguishes from sibling tools like search_conversations and search_summaries.

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 context for each filter option (e.g., default keyword search, 'ip' for semantic search), but does not explicitly state when not to use or mention alternative tools. It offers good guidance on when to use different filters.

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

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

No annotations provided, so the description carries full burden. It explains extraction options and search mode, adding behavioral context beyond the schema, but omits safety aspects like read-only or permissions. No contradiction with annotations (none exist).

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 front-loads the purpose and includes a detailed list of parameters with explanations. While somewhat lengthy, it is well-structured as a docstring and each part serves a purpose.

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

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

Given the tool's complexity (8 parameters, output schema exists), the description covers purpose, parameters, and extraction options thoroughly. It does not need to detail output schema since one is provided, and it includes search mode and filter context.

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

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

Schema description coverage is 0%, but the description explains each parameter thoroughly: query, extract with enum values, limit, domain, importance, thinking_stage, source, and mode with defaults. This adds significant meaning beyond the minimal 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 'Search conversation summaries with hybrid vector + keyword search', specifying both the action and resource. It distinguishes from siblings like 'search_conversations' and 'semantic_search' by mentioning hybrid search.

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

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

The description implies usage for searching summaries but does not explicitly state when to use this tool versus alternatives. It lacks comparisons or exclusions, leaving the agent to infer context.

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

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

No annotations are provided, so the description must fully convey behavior. It mentions vector embeddings and semantic similarity but does not detail output format, pagination, or whether it searches all conversations. It provides core insight but lacks depth on results and limitations.

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

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

The description is three sentences with a clear front-loaded purpose, followed by capability and comparison. No fluff or redundancy. However, the brevity comes at the cost of missing parameter explanations and behavioral specifics, which would improve completeness.

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

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

For a simple search tool, the description covers basic purpose and differentiation. However, with no annotation support and 0% schema description coverage, it fails to explain parameters or provide sufficient behavioral context. The existence of an output schema partially compensates, but the description could be more informative.

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 input schema has 0% description coverage, and the description does not explain the query type or limit's purpose (e.g., maximum results). It adds no meaning beyond what parameter names imply, leaving the agent to infer usage. This is a significant gap given the lack of schema descriptions.

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

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

The description states it searches conversations using semantic similarity, finds conceptually similar messages, and contrasts with keyword search. It clearly identifies the verb (search), resource (conversations), and method (semantic similarity), effectively distinguishing it from sibling tools like search_conversations.

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 explains that the tool is more powerful than keyword search for finding related ideas, implying when to use it. However, it does not explicitly state when not to use it or mention alternatives beyond the implied contrast. The context is clear but lacks explicit exclusion criteria.

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

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

No annotations are provided, so the description carries full burden. It does not explicitly state that the tool is read-only or has no side effects. It mentions output as a 0-1 score but omits details on determinism, auth needs, or rate limits.

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 extremely concise with three sentences, each adding value: purpose, factors, and output format. It is front-loaded and contains no redundant information.

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

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

The description covers the output range and key factors, but lacks details on error handling, input constraints, or usage limits. With a simple tool and no output schema visible, the description is adequate but not fully comprehensive.

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

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

Schema description coverage is 0%, requiring compensation. The description mentions 'domains' and 'switching between domains', which provides context for the two string parameters 'current_domain' and 'target_domain'. However, it does not define what constitutes a domain or provide examples, resulting in only minimal added 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 estimates cognitive switching cost, using specific verbs 'Estimate' and resource 'cognitive cost of switching between domains'. However, it does not explicitly distinguish itself from sibling tools like 'cognitive_patterns' or 'context_recovery', which could overlap.

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. Given 22 sibling tools including 'alignment_check', 'brain_stats', and 'cognitive_patterns', the description lacks usage context or 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 provided, the description carries the full burden for behavioral disclosure. It correctly implies a read-only tracking operation, but does not explicitly state it is non-destructive or mention any other behaviors like permissions or pacing. The existence of an output schema partially compensates for missing return value details.

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

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

The description is concise and front-loaded with the main purpose. The structured 'Args' section with bullet points is clear, though some repetition could be trimmed (e.g., explaining each view option once instead of partly in the main text and again in args).

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

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

Given the tool has only two parameters and an existing output schema, the description provides adequate context for inferring usage. It covers the main purpose and parameter semantics. Minor gaps exist in behavioral and alternative tool guidance, but overall it is complete enough for an agent.

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

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

The description adds significant meaning beyond the input schema: it explains the purpose of 'topic' and provides detailed options for 'view' with their meanings. This compensates well for the 0% schema description coverage.

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

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

The description clearly states what the tool does with a specific verb ('Track') and resource ('evolution of thinking about a topic over time'). This distinguishes it from siblings like 'cognitive_patterns' or 'what_was_i_thinking', which focus on different aspects of thinking.

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

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

The description provides clear context for the 'view' parameter, explaining what each option ('full', 'velocity', 'first') shows. However, it does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or when-not-to-use guidance.

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

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

No annotations are provided, so the description carries the full burden. It mentions that it shows preserved data but does not disclose any behavioral traits like side effects, authorization requirements, rate limits, or response size. It is minimal.

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 short (3 sentences) but includes figurative language ('proving the prosthetic works') that may be unclear. The list in the second sentence is helpful, but overall could be more direct and less metaphorical.

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

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

Given the tool has no parameters and an output schema exists, the description gives a high-level view of what information is shown (conversations, domains, questions, decisions). However, it does not detail the output structure or any return value format, leaving room for ambiguity.

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 input schema has zero parameters, so description does not need to add parameter info. Baseline score of 4 is appropriate for trivial parameter count.

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 provides system-wide stats about preserved items (conversations, domains, questions, decisions). It uses a metaphorical 'proving the prosthetic works' but then specifies concrete categories. However, it does not differentiate from sibling 'brain_stats' which could be similar.

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 a 'everything is okay' view for health checking, but provides no explicit guidance on when to use vs. alternatives, no exclusions or context triggers.

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

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

With no annotations provided, the description carries full burden. It correctly implies a read-only operation by stating it 'shows' data, and details the output contents. However, it does not explicitly confirm no side effects or mention any permissions, which would be ideal for a no-annotation 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, front-loaded with the core purpose, and a bullet-like list of output items. Every word serves a purpose; no unnecessary 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 a single required parameter and an output schema (not shown but implied), the description explains what the tool does and what it returns (total conversations, thinking stage distribution, etc.). It is complete for a simple query tool.

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

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

Schema description coverage is 0%, so the description must explain the single parameter 'domain'. The description focuses entirely on the output and does not clarify what constitutes a 'domain' or provide examples/format hints. This leaves the parameter underspecified.

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 provides a 'meta-view of your engagement with a domain over time' and lists specific data it returns (total conversations, thinking stage distribution, importance peaks, cognitive patterns). This distinguishes it from sibling tools like 'tunnel_state' (likely current state) and 'cognitive_patterns' (broader patterns).

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

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

The description implies usage for historical domain analysis but provides no explicit guidance on when to use this tool versus alternatives like 'tunnel_state' or 'cognitive_patterns'. No exclusions or 'when not to use' information is given.

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?

Without annotations, the description partially conveys read-only behavior through 'reconstruct' and the return list, implying no side effects. However, it does not explicitly state idempotency, safety, or permissions, which limits 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 very concise with three short sentences. The first sentence immediately states the purpose, and the following sentences add detail efficiently without redundant words.

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

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

Given the tool's simplicity (2 params, output schema exists), the description adequately covers purpose, input domain, and output details. It could explicitly state it is a read-only operation, but overall it provides sufficient context.

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

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

The description explains the domain parameter by mentioning 'for a domain', but it does not describe the limit parameter at all. With 0% schema description coverage, the description should provide semantics for both parameters but only partially covers one.

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 reconstructs a cognitive save-state for a domain, listing specific returned fields (thinking stage, open questions, etc.). The gaming analogy aids understanding, but it does not explicitly distinguish from similar sibling tools like context_recovery or what_was_i_thinking.

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 offers no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or scenarios where other tools would be more 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?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states the purpose, with no details on side effects (e.g., mutation), authentication needs, rate limits, or output format. For a read-only search tool, this is insufficient.

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 very short (one line), which is concise but lacks structure. It front-loads the core purpose, but the brevity sacrifices completeness, making it hard for an agent to fully understand the tool.

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

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

Given the tool's simplicity and the presence of a sibling 'open_threads', the description should clarify the filtering logic beyond just 'stage' vs 'all'. It also fails to mention the output schema or return value, leaving the agent uncertain about what it will receive.

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%, yet the description provides no explanation for the two parameters ('domain', 'importance'). The agent gains no additional meaning beyond the schema's default values and types.

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 specifies the tool's purpose: finding conversations in the 'exploring/crystallizing stage' with 'open questions'. It uses a verb ('find') and a clear resource ('conversations'), and distinguishes from siblings like 'open_threads' by adding stage constraints.

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

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

No explicit guidance on when to use this tool versus alternatives. The description implies a use case (unresolved conversations) but does not mention prerequisites, exclusions, or sibling tools that might be more appropriate for different scenarios.

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 full burden. It mentions 'returns integrated timeline' but lacks details on behavior like rate limits, authentication needs, or handling of empty results.

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, front-loaded sentences with no wasted words. Every sentence adds value.

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

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

Given the tool has 2 parameters, an output schema, and many siblings, the description is too sparse. It does not explain the output schema or differentiate from similar tools beyond the broad scope.

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%, yet the description provides no additional meaning for the 'query' and 'limit' parameters. It completely fails to compensate for the lack of 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?

Description clearly states verb 'search' and resource 'ALL sources' (conversations, GitHub, markdown), and specifies the outcome 'integrated timeline of thinking on a topic', distinguishing it from source-specific 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?

No explicit guidance on when to use this tool versus alternatives. It implies a broad search but does not mention when to choose unified_search over source-specific tools like github_search or search_conversations.

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

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

No annotations provided, but description clearly states it returns synthesis with decisions, open questions, quotes, and precedents. Implied read-only, but not explicitly stated.

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

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

Description is concise with no fluff. First sentence states core purpose, second provides parameter details. Well-structured for quick 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?

Tool has an output schema, so return values are handled. However, missing guidance on when to use versus sibling tools like what_was_i_thinking or semantic_search, and no mention of data dependencies or limitations.

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?

Parameter descriptions are provided despite schema having 0% coverage. Topic and mode are explained in detail, including valid mode options and their effects.

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

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

Description provides a specific verb 'synthesize' and resource 'what you think', clearly distinguishing it from sibling search and retrieval tools. The two modes give concrete scope.

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?

Tool describes two modes but does not specify when to use this over alternatives like semantic_search or what_was_i_thinking. No exclusions or prerequisites mentioned.

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

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

No annotations are provided, so the description carries full burden. It labels the tool a 'time-travel snapshot' but does not disclose whether it is read-only, what data it returns, or any side effects. This lack of behavioral context is a significant gap.

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

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

The description is extremely concise, consisting of two brief sentences. It front-loads the core concept and immediately provides the required format, with no wasted words.

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

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

Given a single parameter and an existing output schema, the description sufficiently explains input but omits what the output looks like (e.g., text, structured data) and whether the tool is read-only or has constraints. It meets minimum viability but leaves 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 input schema only defines 'month' as a string with no format. The description adds critical format guidance ('YYYY-MM') and an example, which meaningfully compensates for the schema's lack of description coverage.

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

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

The description clearly states the tool retrieves a snapshot of past thoughts for a given month. It uses a specific verb ('time-travel snapshot') and resource ('what was on your mind'). However, it does not explicitly differentiate from similar sibling tools like 'conversations_by_date' or 'what_do_i_think', which could cause confusion.

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 specifies the required date format (YYYY-MM) but provides no guidance on when to use this tool versus its siblings (e.g., search or conversation retrieval tools). There is no mention of when not to use it or prerequisites.

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