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

No annotations provided; description fully covers behavior: looks up by slug, returns full markdown, typical length, content type, and fallback suggestion. Could mention any side effects or auth requirements, but none are expected for a read-only knowledge module 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 concise (5 sentences) and well-structured: purpose, content type, usage instruction, behavioral note, and example. Every sentence adds value with no 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?

Even without output schema, the description fully explains the return value (complete markdown content, length range, typical sections). It covers all necessary context 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?

Input schema has 100% coverage with description for 'name' parameter. The tool description adds extra value: 'Exact module slug (kebab-case). Get slugs from forage results. Examples: ...' This goes beyond the schema's 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 'Load the full content of a knowledge module by its exact name/slug.' It clearly identifies the verb (load) and resource (knowledge module), and distinguishes from sibling 'forage' by specifying 'Use after forage to read a specific module in full.'

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

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

Explicitly says 'Use after forage to read a specific module in full.' and 'If not found, suggests using forage to search.' Provides clear when-to-use and when-not-to (fallback) 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 full burden. It states 'Behavior: performs hybrid search (full-text + semantic) across the knowledge base, ranks by relevance, returns top N matches.' This adds useful detail beyond the schema but does not disclose auth needs, rate limits, or potential 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?

Description is compact (three sentences plus examples), front-loaded with purpose, then usage, then behavior. No extraneous words. Examples are placed at the end, which is acceptable. Minor improvement could be to separate examples more clearly.

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 low complexity (2 params, no output schema, no annotations), the description is complete: it covers purpose, usage, behavioral details, and examples. No obvious gaps for a search tool. Slightly more detail on pagination or result format would improve, but not necessary.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds marginal value with example queries and advice to 'Be specific' for query, and default/max values for limit. These are helpful but not essential beyond the schema definitions.

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 'Search 500,000+ expert knowledge modules by natural language query' and lists return results. Purpose is specific and actionable. However, it does not differentiate from sibling tool 'research_search' which may have overlapping functionality.

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

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

Explicit guidance: 'Use when the user needs technical guidance, best practices, or domain expertise.' This provides clear context for when to invoke the tool. No alternative tools or exclusion criteria are mentioned, but the guidance is sufficient for a search tool.

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

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

The description thoroughly discloses the tool's output format (narrative, contradictions, outliers, confidence), edge cases (empty outliers indicating confabulation, weak arc for confidence < 0.7), default window (last month), limit (50 entries), and exclusion of superseded entries. No annotations exist, so the description fully carries the behavioral burden.

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 concise 5-sentence paragraph that front-loads the primary purpose and then efficiently covers output structure, warnings, defaults, and limits. Every sentence adds value without redundancy.

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

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

Given the tool has only 2 optional parameters and no output schema or annotations, the description provides comprehensive context: what the tool does, what it returns, when to suspect confabulation, and configuration defaults. This is sufficient for an AI to decide when to invoke the tool and interpret results.

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 already provides descriptions for both parameters (window and max_entries), achieving 100% coverage. The description adds minor value by stating defaults ('default window is last month, max 50'), but does not significantly enhance understanding 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 it builds a coherent arc from recent journal entries, with specific features like anti-confabulation guardrails and a defined output structure (4 keys). It distinguishes itself from sibling tools like journal_recall or journal_introspect by focusing on narrative construction rather than retrieval or self-reflection.

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 constructing a narrative arc from recent entries, but it does not explicitly state when to prefer this tool over siblings or when not to use it. The phrase 'using the configured LLM' hints at its unique capability, but no alternatives or exclusions 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 provided, so the description carries full burden. It discloses key behaviors: refusal for private entries, creation of a new entry with specific structure (preceded_by, content format, tags), and that the LLM writes the reaction. This is 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 fairly concise with two sentences, but the second sentence is lengthy and contains many details. It is front-loaded with the main purpose, but could be slightly more streamlined.

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, the description covers all necessary aspects: purpose, parameter meanings, behavioral outcomes, and failure conditions. No output schema exists, but the description explains the resulting entry structure sufficiently.

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

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

Schema coverage is 100%, but the description adds context beyond the schema: entry_id must refer to a user-shared entry, and user_response is the reply text. This enhances understanding of the parameters' roles.

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: handling a user's reply to a shared entry, triggering an LLM reaction and creating a new reflection entry. It distinguishes from sibling tools like journal_write or journal_introspect by focusing on dialogue interaction.

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 explains when to use the tool (user replies to a shared entry) and when not (refuses if visibility=self). However, it does not explicitly mention alternative tools for similar tasks, though context implies the specific dialogue scenario.

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, but the description fully discloses behavioral traits: it pulls semantically-relevant entries, uses an LLM in first-person voice, restricts to only those entries, returns the answer plus entries_referenced and hallucination_risk score, and explains the risk thresholds and the fallback message when no support is found.

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 and well-structured, with the most important information first. It could be slightly more concise by merging some details, but it is not verbose and 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 complexity of the tool and no output schema, the description covers purpose, behavior, expected output format, error or edge case handling (when no patterns found), and risk scoring. It is complete enough for an agent to understand when and how to use the 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 100%, meaning both params (question, scope) are described in the input schema. The description adds context about the question being a 'self-question' and scope as 'recent (last 14 days) | all', but does not significantly augment the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Ask YOUR journal a self-question' and explains the process of retrieving entries and generating a grounded answer. It distinguishes from sibling tools like journal_recall (which likely retrieves raw entries) and journal_dialogue (which might involve conversation).

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 self-reflection grounded in journal entries, but it does not explicitly state when to use it vs. alternatives like journal_recall or journal_dialogue. The context is clear, but explicit exclusion guidance is missing.

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 fully carries the transparency burden. It discloses embedding-based semantic search, default agent scoping, the inherit_from marking with 'inherited_from' response field, and superseded entry handling. No contradictions with missing annotations.

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

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

The description is concise and front-loaded with the main purpose. It packs several details without verbosity. While dense, it could benefit from slight structuring (e.g., bullet points for defaults), but remains 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 the 8 parameters and no output schema, the description covers most critical aspects: parameter defaults, filtering options, and response markings. It omits details about the response structure beyond the 'inherited_from' field, which is a minor gap for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema: explains 'query' as embedded and cosine-similarity ranked, clarifies include_superseded default, and details inherit_from response behavior. This additional context raises the score.

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 starts with 'Search YOUR journal' and details specific filtering by entry_type, tags, and semantic query, clearly distinguishing it from sibling tools like 'recall' or 'remember' which likely handle broader memory retrieval. The inherit_from clause further specifies predecessor journal access.

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 explains default behavior (own agent_id) and the inherit_from alternative for predecessor journals. It also clarifies the default exclusion of superseded entries. However, it does not explicitly compare to sibling tools or state when NOT to use this tool, though the context is sufficient for an informed 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?

Discloses critical behaviors: per-agent isolation, auto-computed importance, semantic embedding, visibility scoping, and causal chaining. No annotations exist, so the description fully carries the transparency burden without 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?

Front-loaded with purpose and well-structured, but contains minor redundancy (e.g., reiterating visibility). Still, each sentence adds value, and the length is justified by the tool's 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?

Covers all 9 parameters with semantic context, including optional fields like valence_reason and conversation_id. No output schema exists, but the description provides sufficient behavioral insight for a write operation.

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

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

Adds significant meaning beyond the high-coverage schema (89%): explains auto-computation of importance, embedding purpose, causal chain semantics, and conversation_id grouping. This compensates for any missing 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?

Explicitly states the action ('Append a first-person entry') and the resource ('YOUR persistent journal'), distinguishing it from siblings like journal_recall and journal_dialogue.

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

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

Provides clear context for when to use (persistent journaling) and covers key behaviors like auto-computed importance and causal chaining. Could have explicitly contrasted with sibling tools (e.g., absorb) but still offers solid 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 explains the internal behavior: 'queries the module index, groups by category, returns a structured map with counts.' It also notes that no parameters are needed and that it returns the full overview, fully disclosing the tool's 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 concise with four sentences: purpose, content, usage, and behavior/parameter note. Information is front-loaded and every sentence adds value without redundancy.

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

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

Given zero parameters and no output schema, the description fully explains what the tool returns (categories, counts, top modules, total stats) and how it works (queries index, groups by category). This is complete for its complexity level.

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, and the description explicitly confirms 'No parameters needed.' With 100% schema coverage, the description adds no extra meaning but is consistent. Baseline for 0 params is 4.

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

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

The description clearly states the tool's action: 'Browse the entire Celiums knowledge network organized by category.' It specifies the output content (categories, module counts, top modules, total statistics) and distinguishes from sibling tools by focusing on network overview rather than individual records or actions.

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

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

Explicit usage guidance is provided: 'Use to explore what knowledge is available, discover categories, or get an overview of the knowledge base.' While no explicit when-not or alternatives are given, the sibling tools have clearly different purposes, making this sufficient.

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

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

With no annotations, the description fully covers behavioral traits: hybrid retrieval (vector, full-text, emotional), SAR filtering, and returned fields (content, type, importance, relevance score). No contradictions.

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

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

The description is a single focused paragraph with front-loaded purpose, followed by usage and behavior details. Every sentence contributes value without redundancy.

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

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

The description covers all essential aspects for a search tool: what it does, what it returns, parameter semantics, and behavioral details. No gaps given the absence of 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?

Despite 100% schema coverage, the description adds significant value: query example, limit usage guidance (3-5 for focus, higher for comprehensive), and projectId scope details (default current+global, admin requirement for 'all').

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 persistent memory with semantic+emotional ranking, but does not explicitly differentiate from similar sibling tools like 'remember' or 'forage'.

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 specific usage examples ('retrieve previously stored facts, decisions, preferences') and query examples, but does not state when not to use the tool or mention alternatives.

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

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

With no annotations, the description fully compensates by detailing internal behavior: emotional analysis (PAD model), importance scoring, and circadian tracking. This transparency about what happens during storage is exemplary.

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 (4-5 sentences), front-loaded with purpose, and efficiently covers types, behavior, and scoping without waste. 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 no output schema, the description adequately explains the storage process and persistence. It omits details on return values or confirmation, but overall it provides sufficient context 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?

Schema coverage is 100% with good parameter descriptions. The description adds marginal value (e.g., 'richer content enables better semantic recall') but does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it stores information in persistent memory and lists use cases (facts, preferences, decisions, context). It differentiates from siblings by emphasizing storage versus retrieval (e.g., recall), but does not explicitly contrast with other writing or memory tools like absorb, 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 provides clear usage guidance ('Use to save facts, preferences...') and explains scoping via projectId. However, it lacks explicit when-not-to-use instructions or comparisons with sibling tools, leaving the agent to infer when to prefer this over alternatives.

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

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

With no annotations, the description carries the full burden. It clearly indicates a non-destructive export operation generating a markdown memo, but does not mention permissions, side effects, or whether the project must be in a certain state.

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 redundant information. Every word 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?

For a simple tool with no output schema and few parameters, the description covers output content and use cases. It could be more complete by detailing the exact markdown structure or format constraints, but overall it is adequate.

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

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

Schema coverage is 50% (format has a description). The description adds no further meaning to the parameters beyond what the schema provides; 'projectId' remains undefined and format is already explained.

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 'Export the project as a markdown memo' with specific content (question, findings, sources, confidence, gaps), clearly distinguishing it from sibling tools that add or manage individual research components.

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 concrete use cases: sending a brief to a teammate, pasting into Notion, or feeding into an LLM. It implies a summary export role but lacks explicit when-not-to-use guidance or alternatives like using research_finding_add for detailed data.

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 cover behavioral traits. It lists fields (sourceKind, optional ref/url, confidence, notes) and explains the role of findings in the workflow, but does not mention side effects, idempotency, or permissions. Adequate for a simple create 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, front-loaded with purpose, each sentence adds value. No redundancy.

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

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

Given 7 parameters (3 required) and no output schema, the description provides sufficient context: what fields to specify, the workflow (findings as building blocks, export for memo). Complete for a create tool of moderate complexity.

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

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

Schema coverage is 29% (only sourceKind and confidence described). Description adds context for sourceKind (enum values), sourceRef/evidenceUrl as optional, and notes as free-text, but does not describe projectId or claim in detail. Partially compensates for low coverage.

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

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

Clearly states the tool records an atomic claim with evidence into a project. The verb 'record' and resource 'atomic claim with evidence' are specific. It distinguishes from sibling tools like research_export or research_gap_add by focusing on adding individual findings.

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 by describing findings as building blocks and mentioning export consolidates them into a memo, but lacks explicit guidance on when to use this vs alternatives (e.g., research_synthesize). No exclusions or when-not-to-use 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?

With no annotations, the description must bear the burden of behavioral disclosure. It reveals that gaps are first-class and automatically re-attempted, but omits details on side effects, permissions, error handling, or output 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 concise at two sentences, front-loading the core purpose. However, it could be more structured by listing parameters or using bullet points for clarity.

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

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

Given no output schema and moderate complexity (3 params, 2 required), the description is incomplete: it does not explain what the tool returns (e.g., success confirmation, ID) or handle error cases, leaving gaps in agent understanding.

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 3 parameters with 0% description coverage. The description provides context for 'question' and 'whyUnresolved' implicitly, but does not explicitly describe each parameter's meaning or constraints, leaving ambiguity for 'projectId' and 'whyUnresolved'.

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: to flag an unresolved question that couldn't be backed with evidence. It distinguishes itself from sibling tools by emphasizing that gaps are first-class and automatically re-attempted, making the purpose specific and 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 when to use the tool (after searching without finding evidence) and mentions automatic re-attempts, but it lacks explicit when-not-to-use guidance or comparisons to alternatives like research_finding_add.

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 discloses the return data comprehensively, implying a read operation. However, it does not explicitly confirm non-destructiveness or mention authorization needs, leaving slight ambiguity about 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 two sentences, front-loaded with the action and key return details. Every phrase adds value with no redundancy.

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

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

For a tool with one parameter and no output schema, the description covers the purpose, return structure, and usage timing sufficiently. It lacks error handling guidance but is otherwise complete for an agent's decision-making.

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

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

The single parameter 'projectId' is self-explanatory, but schema coverage is 0% and the description adds no additional meaning (e.g., format, source). It is adequate but does not compensate for 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 clearly states the tool resumes context from a paused research project and specifies the exact return data (central question, 50 findings with details, open gaps). This distinguishes it from sibling tools like research_project_create or research_finding_add.

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 says to use this BEFORE asking new questions in an existing project to avoid duplication, providing clear usage context. It does not explicitly name alternatives but implies when not to use (e.g., for new projects).

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 discloses persistence across sessions, depth control with document counts, and that it returns a project_id. It could mention any limitations or authentication needs but is otherwise transparent.

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

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

Three sentences with no wasted words. The key action and return value are front-loaded, and each sentence conveys essential 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?

Despite having no output schema, the description explicitly states the return value (project_id) and its role in subsequent calls. It covers all relevant aspects for a creation tool with four 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 coverage is 100%, so baseline is 3. The description adds significant value by explaining the depth parameter's effect (overview=5 docs, standard=10, deep=20+ with adversarial verification), which goes beyond the schema enum.

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 begins with a clear verb+resource ('Create a persistent research project') and distinguishes itself from siblings like research_project_continue and research_project_list by emphasizing persistence and the project_id return value.

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 explains that the returned project_id can be passed to subsequent research_* calls and details depth options. However, it does not explicitly state when not to use this tool or contrast it with alternatives like research_project_list.

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 cover behavioral traits. It mentions 'list all research projects for a user' but does not disclose whether it requires authentication, is read-only, supports pagination, or what happens when the optional 'userId' is omitted. 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 two sentences with no fluff. The first sentence states the core action and output, and the second provides usage guidance. It is appropriately front-loaded and efficient.

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

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

Given the tool has no output schema, the description provides a reasonable outline of the return data (list of projects with counts). It covers the essential context for a list operation, though it could mention whether results are paginated or ordered. Overall, it is largely complete for the tool's 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?

The schema has one optional parameter 'userId' with 0% description coverage. The description adds meaning by stating it retrieves projects 'for a user,' implying a filter. However, it does not specify that omitting userId likely defaults to the current user, nor does it clarify if this is a required filter for explicit user queries.

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 all research projects for a user, including counts of findings and open gaps. It distinguishes from sibling tools like 'research_project_create' (create) and 'research_finding_add' (add finding) by specifying the output and purpose.

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 includes 'Use to discover what investigations are already in progress,' which provides clear context for when to use the tool. While it does not explicitly list when not to use or mention alternatives, the guidance is sufficient for an AI agent to infer appropriate usage.

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. It discloses the search algorithm and returned fields, but does not state whether the tool modifies data, requires authentication, or has rate limits. The read-only nature is implied but not explicit.

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

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

The description is two concise sentences: the first explains the algorithm and output, the second provides usage context. Information is front-loaded and every sentence adds value without redundancy.

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

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

The description covers purpose, usage, algorithm, and return fields. Without an output schema, it adequately describes the tool. However, it lacks details on pagination, sorting, or handling of empty results, which would enhance 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?

Schema coverage is 100%, so baseline is 3. The description adds minimal parameter guidance beyond what the schema provides; it mentions query is 'natural-language' and limit has defaults, but does not elaborate on category usage or how parameters affect results.

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 a hybrid search across the 'celiums knowledge corpus' using BM25, semantic kNN, and reciprocal rank fusion, and lists the returned fields. It clearly distinguishes from siblings like 'research_synthesize' and 'research_export' by stating 'Use to locate evidence before synthesize.'

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 instructs to 'Use to locate evidence before synthesize,' indicating the context for this tool. While it does not mention alternatives or when not to use it, the sibling list provides some implicit differentiation.

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

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

Given no annotations, the description provides good behavioral detail: uses Opus 4.7 by default, logs query, distinguishes supported claims. Missing potential side effects like cost or rate limits, but otherwise transparent.

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

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

Three focused sentences with front-loaded main action. No unnecessary words. Efficiently communicates core behavior and key features.

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 main behavior, logging, and output distinction. Without output schema, the description adequately implies the return type is an analysis text. Could add error handling or time limits, but sufficient for most agents.

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 already covers 75% of parameters with descriptions. The description adds little beyond schema; for 'query' it says 'research question', which is similar to schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool performs hybrid search and synthesis with citations, distinguishing it from siblings like research_search. The verb 'synthesize' and specific output details make 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 when to use (for a synthesis analysis), but does not explicitly contrast with alternatives like research_search or other tools. No guidance on 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 are provided, so the description must be fully transparent. It describes the behavior: analyzes goal, matches metadata, returns ranked suggestions. It adds context beyond the schema, such as no AI inference. Minor missing details like no mention of authentication or rate limits, but overall strong.

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 at four sentences, well-structured with purpose, usage context, behavioral explanation, and an example. No extraneous 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 tool has one parameter, no output schema, and no annotations, the description is complete. It explains what it does, how it works, when to use it, and provides an example. All necessary context for an agent to use the tool correctly.

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

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

The sole parameter 'goal' is fully described in the schema (100% coverage). The description adds an example but doesn't provide additional constraints or semantics beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose as getting module recommendations based on a goal, with specific verbs ('Get') and resource ('module recommendations'). It distinguishes from sibling 'forage' by noting it's faster for broad exploration, and clarifies it uses keyword matching not AI inference.

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 says when to use: 'when the user describes what they want to achieve and needs guidance on which modules to study.' It also contrasts with the sibling 'forage' for broad exploration, providing clear guidance on 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool is mutating ('create or upsert') and adds context about voice sample, but does not mention error conditions, required permissions, or side effects. More detail needed 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: first clearly states the action, second provides critical context about the voiceSample parameter. No fluff, front-loaded with 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?

With 7 parameters and no output schema, the description is incomplete. It does not explain the upsert behavior (e.g., what determines an update vs. create), return value, or how to handle errors. Leaves significant gaps for the agent.

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

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

Schema description coverage is only 29% (2 out of 7 parameters have descriptions in schema). The description adds value for voiceSample by specifying its purpose and length requirement, but does not explain projectId, name, role, archetype, arcSummary, or physicalDescription 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 'Create or upsert a character' and provides a specific use case for the voiceSample parameter. It is distinct from sibling tools like write_scene_create or write_project_create.

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 (for creating/upserting characters) and emphasizes the importance of the voiceSample parameter for continuity_check. However, it does not explicitly state when not to use it or name alternatives.

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

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

With no annotations provided, the description carries full burden. It explains the loading process (target scene, prior 20 scenes, characters, worldbuilding) and output format (JSON list of issues with fields). It does not disclose side effects or performance, but for a read-only analysis tool, this is adequate. No contradiction with annotations.

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

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

The description is concise with three sentences. It front-loads the signature feature, lists inputs and outputs, and includes a comparative statement. Every sentence earns its place without redundancy.

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

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

Given the tool's complexity (3 parameters, no output schema, no annotations), the description covers inputs, outputs, and purpose. It could mention error handling or more detail on return format, but it is largely complete for an AI agent to understand and invoke 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 67% (sceneId and scopeChapters described). The description adds context by explaining that scopeChapters defaults to 20 and that the tool loads 'prior 20 scenes,' which aligns with the parameter. It does not explicitly explain projectId, but overall the description adds semantic value beyond the schema.

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

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

The description clearly states the tool performs a 'structural continuity check' and lists specific issue types it outputs. It distinguishes itself from sibling tools by emphasizing 'NO other writing tool does this — Sudowrite/Grammarly/ProWritingAid are line-by-line, this is structural.' The verb 'check' and resource 'continuity' are precise.

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 when-to-use guidance by contrasting with line-by-line tools. However, it does not explicitly state when not to use it or provide alternatives among sibling tools. The differentiation from external tools is strong but internal sibling context is 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?

Describes output structure in detail (scenes ordered, grouped by chapter, with markers). No annotations, so description carries full burden, which it handles well.

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

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

Two sentences, front-loaded with action and format, then details. 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?

Adequately covers output and usage for a simple export tool. Minor missing details on errors or return format, but sufficient for likely use cases.

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 50% (format described). Description does not mention parameters, leaving projectId undefined. Does not add meaning beyond schema.

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

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

Clearly states it exports a project as a markdown manuscript, with specific structural details. Differentiates from research_export by context, though not 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?

Provides usage context: clean preview or for later import into other tools. Does not contrast with siblings or state when not to use.

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. Description mentions return of project_id and structureTemplate usage, but lacks detail on side effects, idempotency, or error cases.

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 purpose. No redundancy, but second sentence could be more concise as parameter info.

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 6 parameters and no output schema. Description doesn't explain return format, parameter constraints, or usage context (e.g., required title).

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 low (17%). Description only adds meaning for structureTemplate; other parameters (userId, title, genre, premise, wordTarget) are not described beyond their names.

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

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

Clearly states action (create), resource (writing project), and role as prerequisite for other write_* tools. Distinguishes from siblings like write_character_create.

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?

Explains when to use (create project) and implies necessity for other tools. No explicit when-not-to-use or alternatives, but clear 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?

Discloses the tool returns metadata, all characters, scene count, word count, and 5 recent scenes. No side effects or destructive behavior implied. For a read-only retrieval tool without annotations, this is transparent and adequate.

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

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

Two concise sentences with no filler. The first sentence lists contents, the second provides usage guidance. All information is front-loaded and earns its place.

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

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

For a simple single-parameter retrieval tool with no output schema, the description fully covers purpose, returned data, and usage context. No additional details are needed for an agent to select and 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?

The description does not explain the projectId parameter beyond implying it identifies the project. With 0% schema coverage, the description should add details like format or constraints, which it omits.

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

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

Clearly states the tool retrieves the full project state, listing specific components (metadata, characters, counts, recent scenes). Distinct from siblings like write_project_create or recall which focus on creation or 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?

Explicitly advises 'Use to orient yourself when resuming work,' providing clear context for when to invoke. Does not mention when not to use or alternatives, but the guidance is helpful.

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 mentions that certain fields enable continuity check but does not disclose side effects (e.g., does it shift other scenes?), expected output, authentication requirements, or error conditions. The behavioral disclosure 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 two sentences with no wasted words. The first sentence front-loads the primary action, and the second adds contextual guidance. 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 complexity (11 parameters, no output schema, no annotations), the description is adequate but not thorough. It covers the tool's core purpose and key optional fields but lacks details on required parameters, expected return value, or behavior when position is invalid. It is sufficient for basic use but might leave gaps for complex scenarios.

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

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

Schema description coverage is only 36% (4 of 11 parameters have descriptions). The description adds semantic value by explaining that povCharacterId, locationId, and timeMarker together enable continuity check, and that sceneGoal, conflict, and outcome are optional but recommended. However, it does not explain projectId, chapterId, beatIdTarget, or content beyond what the schema provides.

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: 'Insert a scene at a specific position.' It identifies the resource (scene) and the context (position), and distinguishes it from sibling tools like `write_scene_update` by focusing on creation with a position parameter.

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 optional fields (for continuity check and revision suggestions) but does not explicitly state when to use this tool versus alternatives like `write_scene_update`. No exclusion criteria or prerequisites 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?

Discloses automatic snapshotting and version counter bumping, which are key side effects. However, with no annotations, it lacks details on permissions, failure modes, or reversibility.

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, each adding value: purpose, snapshotting behavior, version bumping. 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?

Tool is simple with 2 params, but description omits return value and error conditions. Adequate but not 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%, and the description provides no additional meaning for sceneId or content beyond their names 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?

Description starts with 'Replace a scene's content.' which is a clear verb+resource. It distinguishes from write_scene_create and adds context about automatic snapshotting and version bumping.

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 vs sibling tools. Implies it is for updating existing scenes, but does not state prerequisites or compare to alternatives like write_scene_create.

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