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

With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: maximum 50 chapters per document constraint, positioning options with default value, and return format structure. It also mentions 'Maintains document flow' as a behavioral characteristic. The only gap is lack of explicit mention about whether this is a write/mutation 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 well-structured with clear sections but contains some redundancy. The 'Position options' line repeats what's in the schema enum, and the 7-point 'You should' list includes some generic advice ('Include practical, actionable content') that doesn't add tool-specific value. However, it's front-loaded with the core 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 mutation tool with no annotations and no output schema, the description does well by explaining the return format, constraints (max 50 chapters), and behavioral context. It could be more complete by explicitly stating this is a write operation and mentioning potential error conditions beyond what's implied in the return format.

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. The description adds meaningful context beyond the schema: explains the purpose of 'reference_chapter' for precise placement, clarifies that position options are for 'before/after/end' (though schema already has enum), and provides guidance on how to use parameters effectively (e.g., 'Choose clear, descriptive chapter titles').

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

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

The description clearly states the specific action ('Add a new chapter to an existing knowledge document') and distinguishes it from siblings like 'create_knowledge_file' (creates new file) and 'update_chapter' (modifies existing chapter). It includes the key differentiator of 'positioning control' which is not present in other 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?

The description provides explicit 'When to use this tool' with 5 specific use cases and 'DO NOT use when' with 3 clear exclusions. It also implicitly distinguishes from alternatives like 'update_chapter' (for modifying existing chapters) and 'create_knowledge_file' (for creating new documents).

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 and does well by disclosing key behavioral traits: 'Non-destructive addition' (safety), 'Maintains document structure and flow' (system behavior), 'Flexible positioning' (capabilities), and 'Returns: {success: bool, message?: str, error?: str}' (output format). It doesn't mention rate limits or authentication needs, but covers most essential aspects.

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 clear sections (When to use, Key features, You should, DO NOT use, Position options, Returns) and front-loads the core purpose. While somewhat lengthy, each section earns its place by providing valuable guidance rather than 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?

For a tool with 5 parameters, no annotations, and no output schema, the description provides excellent completeness. It covers purpose, usage guidelines, behavioral traits, parameter context, and explicitly documents the return format. Given the complexity and lack of structured metadata, this description leaves few 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 100%, so the baseline is 3. The description adds some value by explaining 'Position options: "before", "after", "end" (default)' and suggesting 'Use reference_header for precise placement' in the guidelines, but doesn't provide significant additional parameter meaning beyond what the schema already documents.

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 'adds a new section to the project main.md file with precise positioning control.' It specifies the exact resource (project main.md file), action (add section), and distinguishes from sibling tools like update_project_section and remove_project_section by emphasizing creation rather than modification or deletion.

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 'When to use this tool' with 5 specific scenarios and 'DO NOT use when' with 3 clear exclusions, including naming the alternative tool (update_project_section). This gives comprehensive guidance on when to choose this tool versus alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the tool auto-increments task numbers, preserves existing task order, supports rich formatting, and returns a structured response with success status, task number, and messages. It also implies mutation (adding tasks) and includes implementation guidance. The only minor gap is lack of explicit mention of permissions 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 well-structured with clear sections (purpose, usage guidelines, features, instructions, exclusions, returns) and front-loaded key information. While comprehensive, some sections like the 7-point 'You should' list could be more concise. Overall, most sentences earn their place by adding 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 (mutation operation with 4 parameters, no annotations, no output schema), the description provides excellent completeness. It covers purpose, usage scenarios, behavioral traits, parameter guidance, exclusions, and return format. The explicit return format description compensates for the lack of output schema, making this highly complete for 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?

Schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description adds some context about parameter usage (e.g., 'Use clear, actionable task titles (max 200 chars)' for the title parameter, 'Include implementation details in content' for content), but doesn't provide significant semantic value beyond what's in the schema. This meets the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose with specific verb ('Add') and resource ('new task to an existing TODO list'), distinguishing it from siblings like 'create_todo' (creates new TODO lists) and 'complete_todo_task' (marks tasks as done). The mention of 'full markdown support' adds further specificity.

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

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

The description provides explicit guidance with dedicated 'When to use this tool' and 'DO NOT use when' sections, listing specific scenarios for use (e.g., 'Expanding existing TODO with new tasks') and clear exclusions (e.g., 'TODO doesn't exist', 'Task duplicates existing one'). This gives comprehensive context for when to choose this tool 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 provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: marks task with completion timestamp, updates TODO completion percentage, preserves task content and history, and explicitly states 'Cannot be undone'. This provides crucial context about the tool's effects beyond basic functionality.

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 clear sections (purpose, when to use, key features, guidelines, exclusions, returns). While comprehensive, some sections like the numbered 'You should' list could be more concise. Overall, it's appropriately sized for 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?

Given the mutation nature of the tool (completing tasks), no annotations, and no output schema, the description provides excellent contextual completeness. It covers purpose, usage scenarios, behavioral effects, guidelines, exclusions, and return format. This is comprehensive for a tool with this level of complexity.

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

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

The schema description coverage is 100%, so the schema already documents all three parameters. The description doesn't add any additional parameter-specific information beyond what's in the schema. It focuses on usage guidelines and behavioral context rather than parameter semantics.

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 specific action ('Mark a task as completed') and resource ('in a TODO list'), distinguishing it from sibling tools like 'add_todo_task', 'remove_todo_task', or 'get_todo_tasks'. It goes beyond the tool name/title by specifying the exact operation.

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 'When to use this tool' and 'DO NOT use when' sections with detailed scenarios, including alternatives (e.g., not using when task is partially complete). It gives clear context for when this tool is appropriate versus when it should be avoided.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: automatic filename sanitization (spaces→hyphens), support for up to 50 chapters, and the return format (success, document_id, message, error). However, it lacks details on permissions, rate limits, or error conditions beyond the return structure.

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 clear sections (purpose, when to use, key features, guidelines, exclusions) and uses bullet points for readability. It is appropriately sized but could be slightly more concise by integrating some repetitive elements like the chapter requirements.

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 (6 required parameters, no annotations, no output schema), the description is largely complete. It covers purpose, usage, behaviors, and return format. However, it lacks explicit details on error handling or system constraints, which would enhance completeness for a creation 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%, so the schema already documents all six parameters thoroughly. The description adds minimal parameter-specific semantics, only noting that chapters require 'title' and 'content' keys and that filenames get slugified with .md extension optional. This meets the baseline for high schema coverage without significant added value.

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 creates a 'structured knowledge document with rich metadata and chapters', specifying both the verb ('create') and resource ('knowledge document') with distinctive features like chapters and metadata. It differentiates from siblings like 'add_chapter' or 'update_chapter' by focusing on initial document creation.

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 'When to use this tool' with five specific scenarios (e.g., documenting technical topics, creating reference guides) and 'DO NOT use when' with four clear exclusions (e.g., content belongs in main.md, document already exists). It also mentions searching first to avoid duplicates, offering practical 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 and discloses key behavioral traits: it creates new items (implies mutation), supports markdown and hierarchical organization, auto-increments TODO numbers, and returns a specific response format. It doesn't cover permissions or rate limits, but provides substantial operational context.

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

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

The description is well-structured with sections (key features, usage guidelines, do-not-use cases) and bullet points, but could be more front-loaded. Some sentences (e.g., 'Break complex work into subtasks') are more user guidance than tool description, slightly reducing efficiency.

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 creation tool with no annotations and no output schema, the description is fairly complete: it explains purpose, usage, behavioral traits, and return format. It could benefit from more detail on error handling or permissions, but covers core aspects adequately given the 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 100%, so the schema already documents all parameters. The description mentions 'optional initial tasks' and 'tasks need {title: str, content?: str} format', which aligns with but doesn't add significant meaning beyond the schema. Baseline 3 is appropriate as the schema does the heavy lifting.

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 creates a new TODO list with optional initial tasks and rich markdown support. It distinguishes from siblings like 'add_todo_task' (which adds to existing lists) and 'list_todos' (which retrieves lists), making the purpose specific and differentiated.

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

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

The description provides explicit 'When to use this tool' scenarios (e.g., user explicitly requests, planning multi-step tasks) and 'DO NOT use when' exclusions (e.g., user hasn't explicitly asked, trivial tasks). It also implicitly distinguishes from siblings by focusing on creation rather than modification or retrieval.

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 and does well by disclosing key behavioral traits: the action is permanent/cannot be undone, removes from search index, and requires verification steps. It doesn't mention authentication needs, rate limits, or error handling specifics, but covers the critical destructive nature thoroughly.

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 clear sections (purpose, usage guidelines, features, steps, exclusions, returns) and front-loaded with the most critical information. Some redundancy exists (e.g., '.md extension' appears twice), but overall it's appropriately sized with each section earning 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 destructive tool with no annotations and no output schema, the description provides substantial context: clear purpose, usage guidelines, behavioral transparency about permanence, and return value documentation. It doesn't fully explain error scenarios or authentication requirements, but covers the essential aspects given the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents both parameters fully. The description adds minimal value beyond the schema - it mentions '.md extension' for filename (already in schema) and suggests verifying document existence, but doesn't provide additional semantic context about parameters like project_id significance.

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 specific action ('permanently delete') and resource ('knowledge document'), distinguishing it from sibling tools like 'create_knowledge_file' or 'update_chapter'. It goes beyond just restating the name/title by emphasizing the irreversible nature of the action.

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

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

The description provides explicit guidance with 'When to use this tool' (four specific scenarios) and 'DO NOT use when' (three explicit exclusions). It also mentions alternatives like updating instead of deleting, helping the agent choose between this and tools like 'update_chapter' or 'update_project_main'.

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 and excels. It discloses critical behavioral traits: 'IRREVERSIBLE operation', 'Permanently delete', 'This action CANNOT be undone', and details what gets destroyed (project directory, index, knowledge files, TODOs). It also includes safety guidance like requiring user confirmation and backup considerations.

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 clear sections (warning, usage guidelines, features, action items, exclusions) and every sentence earns its place. It's appropriately sized for a high-risk operation, though slightly verbose with numbered lists that could be more concise.

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 destructive tool with no annotations and no output schema, the description provides exceptional completeness. It covers purpose, usage scenarios, behavioral consequences, safety protocols, exclusions, and even specifies the return format despite no output schema. This fully compensates for the lack of structured metadata.

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

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

Schema description coverage is 100% with one parameter clearly documented. The description adds meaningful context beyond the schema by emphasizing 'Verify project_id is correct' and linking it to the irreversible nature of the operation. However, it doesn't provide additional format or validation details beyond what the schema already specifies.

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 'Permanently delete a project and all its content' - a specific verb ('delete') with clear resource ('project and all its content'). It distinguishes from sibling tools like delete_knowledge_file and delete_todo by specifying it removes the entire project directory, index, knowledge files, and TODOs.

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 'When to use this tool' with four specific scenarios and 'DO NOT use when' with four clear exclusions. It offers comprehensive guidance on when to choose this tool versus alternatives like backup or confirmation steps.

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 and does well by disclosing key behavioral traits: it's a destructive operation ('permanent removal'), removes all associated tasks, frees up TODO numbers, and requires verification steps. It doesn't mention rate limits, authentication needs, or error handling specifics, but covers the critical destructive nature adequately.

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 clear sections (purpose, usage guidelines, features, steps, exclusions, returns) and front-loaded with the core action. Some redundancy exists (e.g., 'permanent removal' repeated), but overall it's efficient with every sentence adding 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?

For a destructive tool with no annotations and no output schema, the description provides strong context: clear purpose, detailed usage guidelines, behavioral transparency about permanence, and return value documentation. It doesn't specify error conditions or response formats beyond the basic return structure, but covers most critical aspects given the complexity.

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

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

Schema description coverage is 100%, so the schema already documents both parameters ('project_id' and 'todo_number'). The description doesn't add any parameter-specific semantics beyond what the schema provides (e.g., no clarification on TODO number uniqueness or project context). Baseline 3 is appropriate when schema does the heavy lifting.

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 specific action ('Delete an entire TODO list and all its tasks permanently'), identifies the resource ('TODO list'), and distinguishes it from sibling tools like 'remove_todo_task' which only removes individual tasks. It goes beyond the tool name/title by specifying the scope of deletion.

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 'When to use this tool' with five specific scenarios, 'DO NOT use when' with three clear exclusions, and implicit alternatives (e.g., 'remove_todo_task' for partial deletion). This comprehensive guidance helps the agent choose appropriately among sibling tools.

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 and delivers substantial behavioral context. It discloses key traits: memory efficiency for large documents, case-sensitive exact title matching, navigation info in returns, and caching recommendations. It doesn't mention error handling or performance characteristics, keeping it from a perfect score.

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 clear sections (purpose, when to use, key features, instructions, exclusions, returns) and every sentence earns its place. It's comprehensive yet avoids redundancy, with the most critical information (purpose and basic usage) appearing first.

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 read operation with no annotations but 100% schema coverage, this description provides excellent contextual completeness. It explains when to use the tool, behavioral characteristics, parameter usage rules, sibling relationships, and detailed return structure (even without an output schema), leaving minimal 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?

Schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description adds some value by explaining the title/index mutual exclusivity ('Specify either title OR index, not both') and providing usage guidance ('Use chapter_title for known chapters'), but doesn't add significant semantic details 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 tool's purpose with specific verbs ('Retrieve a single chapter's content') and resources ('by title or index'), distinguishing it from siblings like list_chapters (which lists multiple chapters) and get_knowledge_file (which retrieves entire documents). The opening sentence provides precise, actionable intent.

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 explicit 'When to use this tool' and 'DO NOT use when' sections, providing clear positive and negative guidance. It names alternatives (get_next_chapter for sequences) and specifies prerequisites (knowing chapter title or index), making it highly actionable for an AI agent.

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

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

With no annotations provided, the description carries full burden and adds valuable behavioral context beyond basic functionality. It discloses memory implications ('loads entire document into memory'), performance considerations for large documents, caching advice, and prerequisites like checking document existence. However, it doesn't mention error handling or rate limits, leaving some 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 is well-structured with clear sections (purpose, usage guidelines, features, recommendations, exclusions, returns) and front-loaded key information. While comprehensive, some sentences could be more concise (e.g., 'Returns complete document with all chapters' and 'Full content access' are somewhat redundant). Overall, it's efficient but has minor verbosity.

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 no annotations and no output schema, the description does an excellent job covering behavioral aspects, usage scenarios, and limitations. It explains what the tool returns (including the return structure) and provides practical guidance. The main gap is the lack of explicit error handling details, but otherwise it's nearly complete for this 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 100%, so the schema already documents both parameters (filename, project_id) with their constraints. The description adds minimal value beyond the schema: it reiterates the .md extension requirement (already in schema) and mentions checking document existence (not parameter-specific). This meets the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose with specific verbs ('retrieve complete content') and resources ('knowledge document'), distinguishing it from siblings like get_chapter (partial content) and search_knowledge (searching). It explicitly mentions what it returns (metadata, chapters, structure), making its scope 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 provides explicit guidance with dedicated sections: 'When to use this tool' lists four specific scenarios, 'You should' offers six actionable recommendations, and 'DO NOT use when' names three alternatives (get_chapter, chapter operations, search_knowledge). This clearly defines when to use this tool versus siblings.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: 'Returns null if at end,' 'Maintains reading context,' 'Efficient sequential access,' and the return structure. However, it lacks details on error handling or performance characteristics.

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 clear sections (purpose, usage, features, instructions, exclusions, returns) and uses bullet points for readability. It is slightly verbose in the 'You should' section but overall 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?

For a tool with no annotations and no output schema, the description provides substantial context: clear purpose, usage guidelines, behavioral traits, and a detailed return structure. It compensates well for the lack of structured data, though it could mention error cases or dependencies.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal value beyond the schema, mentioning 'Use current_chapter_title OR current_index' but not explaining the relationship further. This meets the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose as 'Get the next chapter after the current one in sequence,' which is a specific verb+resource combination. It distinguishes itself from siblings like 'get_chapter' (specific chapter access) and 'list_chapters' (bulk listing) by focusing on sequential progression.

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

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

The description provides explicit guidance with a 'When to use this tool' section listing four scenarios and a 'DO NOT use when' section with three clear exclusions. It distinguishes usage from alternatives like 'get_chapter' for non-sequential access, offering comprehensive context.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: returns the first incomplete task, indicates when all are complete, maintains sequence, and requires marking tasks complete before getting the next. However, it lacks details on error handling or performance aspects like rate limits, though these are less critical for a read-only 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 well-structured with sections like 'When to use this tool,' 'Key features,' 'You should,' and 'DO NOT use when,' making it easy to scan. However, it includes some redundancy (e.g., 'Get the next incomplete task' is reiterated in 'Key features'), and the bullet points could be more concise, slightly reducing efficiency.

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 annotations and no output schema, the description does a good job covering purpose, usage, and behavior. It includes return value details in 'Returns,' which compensates for the lack of output schema. However, it could benefit from more context on error cases or integration with sibling tools like 'complete_todo_task,' making it slightly incomplete.

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 100% description coverage, clearly documenting both parameters ('project_id' and 'todo_number'). The description does not add any parameter-specific information beyond what the schema provides, such as explaining how these IDs relate to task sequencing. This meets the baseline of 3 for high schema coverage.

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

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

The description clearly states the tool's purpose as 'Get the next incomplete task in a TODO list for sequential execution,' which includes a specific verb ('Get'), resource ('next incomplete task'), and scope ('sequential execution'). It distinguishes from sibling tools like 'get_todo_tasks' (which likely returns all tasks) and 'complete_todo_task' (which modifies tasks).

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

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

The description provides explicit guidance with 'When to use this tool' (e.g., 'Working through TODO sequentially') and 'DO NOT use when' (e.g., 'Need specific task (not next)'), including alternatives like avoiding it for 'full TODO overview' (which suggests using 'get_todo_tasks' instead). This clearly differentiates usage from other tools.

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 and does well by disclosing key behaviors: it 'auto-detects project from git repository or directory name', 'replaces need for local CLAUDE.md files completely', 'returns structured content with sections for easy parsing', and provides the return format. It doesn't mention error handling beyond the return structure or rate limits, but covers most essential behavioral aspects for a read 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 well-structured with clear sections (purpose, when to use, key features, instructions, exclusions, return format). It's appropriately sized for the tool's importance, though some bullet points could be more concise. Every sentence adds value, and critical information is front-loaded.

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

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

Given the tool's complexity (central project instructions retrieval with migration guidance) and no annotations or output schema, the description provides comprehensive context. It explains the tool's role in the workflow, behavioral expectations, usage scenarios, and return format. The description fully compensates for the lack of structured metadata.

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% (the single parameter 'project_id' has a description), so the baseline is 3. The description doesn't add significant meaning beyond what the schema provides about the parameter, though it mentions 'auto-detects project from git repository or directory name' which provides context about how project_id might be determined.

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 with specific verb ('Retrieve') and resource ('main.md content for a project's central instructions and configuration'). It distinguishes from siblings like 'get_chapter' or 'get_knowledge_file' by focusing on the central project instructions file. The description goes beyond the name/title to explain what 'main.md' represents.

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

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

The description provides explicit guidance on when to use ('ALWAYS use FIRST when starting work on any project', 'Refreshing understanding', 'Checking for updates', 'Migrating from local CLAUDE.md files') and when NOT to use ('already have the project content loaded', 'working with temporary or test projects'). It also references alternatives implicitly by mentioning migration from local files.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key features (e.g., returns version information, shows storage path configuration, provides server description, lightweight status check) and usage behaviors (e.g., use for initial connection verification, include in bug reports), though it could add more on error handling or performance. No contradictions with annotations 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 is well-structured with sections like 'When to use this tool', 'Key features', 'You should', and 'DO NOT use when', but it is somewhat verbose with repetitive points (e.g., debugging mentioned multiple times). Some sentences could be condensed to improve efficiency without losing 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 the tool's simplicity (0 parameters, no output schema, no annotations), the description is largely complete, covering purpose, usage, and return values. However, it lacks details on error cases or specific server capabilities, which could enhance context for an AI agent in edge 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?

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately focuses on usage and output without redundant parameter details, earning a baseline score of 4 for handling this efficiently.

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 showing server information including version from package.json, which is a specific verb+resource combination. However, it doesn't explicitly distinguish this from sibling tools like 'get_storage_status' beyond the 'DO NOT use when' section, which mentions it but doesn't fully articulate the functional difference.

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

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

The description provides explicit guidance on when to use this tool (e.g., checking server version, debugging connection issues, initial connection verification) and when not to use it (e.g., when needing git status, to sync storage, or if information is already known), including a named alternative ('get_storage_status'). This covers both positive and negative scenarios comprehensively.

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 and does well. It explains what information the tool provides (uncommitted file count, current branch, etc.), when to use it (before sync operations, debugging), and what it returns. It doesn't mention rate limits or authentication needs, but for a read-only status tool, this is acceptable.

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

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

The description is well-structured with clear sections (purpose, when to use, key features, usage instructions, exclusions, return values). While somewhat lengthy, every section adds value. The information is front-loaded with the core purpose first.

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 0-parameter tool with no annotations and no output schema, the description provides excellent completeness. It explains the tool's purpose, when to use it, what information it provides, and details the return structure. This fully compensates for the lack of structured metadata.

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 0 parameters with 100% schema description coverage, so the baseline would be 4. The description appropriately doesn't discuss parameters since none exist, which is correct for this case.

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: 'Shows git status of the knowledge datastore.' It specifies the exact resource (knowledge datastore) and action (shows git status). It distinguishes from siblings like 'get_server_info' by focusing specifically on git status rather than general server information.

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

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

The description provides explicit guidance with 'When to use this tool' (5 specific scenarios) and 'DO NOT use when' (3 exclusion criteria). It clearly differentiates from alternatives like 'get_server_info' by stating not to use when 'Just need server info' or 'Don't need git details.'

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: it returns all tasks with content, completion status, rich markdown, task numbers, and order. It also outlines prerequisites ('Use TODO number from list_todos') and operational guidance (e.g., 'Review all tasks before starting', 'Check task dependencies'). However, it lacks details on error handling, rate limits, or authentication needs, which are important for a tool with 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?

The description is well-structured with sections like 'When to use this tool', 'Key features', 'You should', and 'DO NOT use when', making it easy to scan. However, it is verbose with redundant points (e.g., 'Returns all tasks with content' and 'Provides task numbers and order' overlap with 'Key features'). Some sentences, like 'Understanding task requirements' and 'Getting comprehensive task view', add little value and could be condensed for better conciseness.

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 (2 parameters, no annotations, no output schema), the description provides substantial context: it explains the tool's purpose, usage guidelines, behavioral traits, and even includes a return value example ('Returns: {success: bool, todo: {...}, tasks: [...], error?: str}'). This compensates well for the lack of structured fields. However, it could improve by detailing error conditions or response formats more explicitly, especially without an 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?

The input schema has 100% description coverage, with clear documentation for both parameters ('project_id' and 'todo_number'). The description does not add any parameter-specific information beyond what the schema provides, such as format examples or constraints. However, it implies the need for a valid 'todo_number' from 'list_todos', which adds minimal context. Given the high schema coverage, a baseline score 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: 'Get all tasks in a TODO list with their completion status and full content.' It specifies the verb ('Get'), resource ('tasks in a TODO list'), and key attributes ('completion status and full content'). It distinguishes from sibling tools like 'get_next_todo_task' by emphasizing it returns 'all tasks' rather than just the next one.

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

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

The description provides explicit guidance on when to use and when not to use this tool. It lists specific use cases (e.g., 'Reviewing full TODO list details', 'Planning task execution order') and explicitly states 'DO NOT use when: - Only need next task - TODO doesn't exist - Just need TODO overview'. It also references sibling tool 'list_todos' for obtaining TODO numbers, offering clear 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 and does well by disclosing key behavioral traits: 'Lightweight operation (no content loading)', 'Returns titles and summaries only', 'Shows chapter count and order', and 'Enables informed navigation'. It doesn't mention error conditions or performance characteristics, keeping it from a perfect score.

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 clear sections (purpose, when to use, key features, guidelines, exclusions, returns) but could be more concise. Some bullet points could be combined (e.g., 'Getting document overview' and 'Understanding document structure' are similar). Every sentence adds value, but there's minor 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 read-only list operation with 2 parameters and 100% schema coverage, the description is exceptionally complete. It provides comprehensive usage guidance, behavioral context, and explicitly documents the return structure despite no output schema. The description fully compensates for the lack of annotations.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters. The description adds minimal value beyond the schema by mentioning '.md extension in filename' in the 'You should' section, but doesn't provide additional semantic context about parameter usage or interactions.

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 specific action ('List all chapters') and resource ('in a knowledge document'), specifying what information is returned ('titles and summaries only'). It distinguishes from sibling tools like get_knowledge_file and get_chapter by emphasizing it doesn't load 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 provides explicit 'When to use this tool' with 5 specific scenarios, a 'You should' section with 5 actionable guidelines, and a 'DO NOT use when' section with 3 clear exclusions. It explicitly contrasts with get_knowledge_file for large documents.

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 key behavioral traits: it's a 'lightweight overview operation' that returns 'completion statistics' and 'TODO numbers for reference.' However, it lacks details on permissions, rate limits, error handling, or pagination. The description adds value but does not fully compensate for the absence of annotations.

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

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

The description is structured with sections like 'When to use this tool,' 'Key features,' 'You should,' and 'DO NOT use when,' which aids readability. However, it is verbose with repetitive points (e.g., multiple mentions of 'TODO numbers' and 'completion'), and some sentences could be more concise. It is front-loaded with the core purpose, but the length is excessive for the tool's simplicity.

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 low complexity (one parameter, no output schema, no annotations), the description is quite complete. It covers purpose, usage guidelines, behavioral traits, and return format. However, it lacks details on error cases or advanced behaviors, and the output format is described but not in a structured schema. For a simple list tool, 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 input schema has 100% description coverage, with the single parameter 'project_id' documented as 'The project identifier.' The description does not add any meaning beyond this, as it does not mention parameters at all. With high schema coverage, the baseline score of 3 is appropriate, as the description does not enhance parameter understanding.

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: 'List all TODO lists in a project with their completion status.' It specifies the verb ('List'), resource ('TODO lists'), and scope ('in a project'), but does not explicitly differentiate from sibling tools like 'get_todo_tasks' beyond the 'DO NOT use when' section. The purpose is clear but sibling differentiation is not fully integrated into the core description.

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

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

The description provides explicit usage guidelines with 'When to use this tool' listing five scenarios, 'You should' with five numbered recommendations, and 'DO NOT use when' with three exclusions including a named alternative ('get_todo_tasks'). This comprehensive guidance clearly indicates when to use this tool versus 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 and does well by disclosing key behavioral traits: it specifies that removal is permanent, preserves other chapters, maintains document integrity, requires case-sensitive chapter titles, and suggests verification steps. It doesn't mention authentication needs, rate limits, or error handling details, keeping it from a perfect score.

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 clear sections (purpose, usage guidelines, features, instructions, exclusions, returns) and front-loaded key information. It's appropriately sized but could be slightly more concise by integrating some bullet points into flowing text without losing 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?

For a destructive tool with no annotations and no output schema, the description does well by covering purpose, usage context, behavioral traits, and return format. It lacks details on error scenarios or system-level constraints, but given the tool's moderate complexity, it provides sufficient context for effective 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?

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds minimal value beyond the schema by implying the 'chapter_title' must be exact and case-sensitive, but doesn't provide additional context for 'filename' or 'project_id'. Baseline 3 is appropriate when schema does the heavy lifting.

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 specific action ('Remove a specific chapter') and resource ('from a knowledge document'), distinguishing it from siblings like 'delete_knowledge_file' (whole file deletion) and 'update_chapter' (modification rather than removal). It precisely defines the tool's function without ambiguity.

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

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

The description provides explicit guidance with dedicated 'When to use this tool' and 'DO NOT use when' sections, listing specific scenarios like removing outdated content or consolidating overlapping chapters, and warning against use when chapters should be updated instead. It clearly differentiates from alternatives like 'update_chapter' for content modification.

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 and does well: it discloses behavioral traits like 'Precise section removal', 'Preserves all other content', and 'Clean removal without traces'. It also provides implementation guidance (e.g., 'Verify section exists before removal'). However, it doesn't mention error conditions, permissions needed, or rate limits, leaving some behavioral aspects uncovered.

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 clear sections ('When to use', 'Key features', 'You should', 'DO NOT use', 'Returns'), but could be more concise. Some points in 'You should' (e.g., 'Document why section is being removed') are implementation advice rather than essential tool description, slightly reducing efficiency.

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 destructive tool with no annotations and no output schema, the description does well by explaining the tool's behavior, usage guidelines, and return format. However, it lacks details on error handling (beyond the return structure) and doesn't explicitly state this is a mutation operation, though that's implied by 'Remove'. Given the complexity, it's mostly complete but has minor gaps.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds minimal value beyond the schema: it mentions 'exact section header with "## " prefix' which is already in the schema's pattern, and implies the section must exist (in 'You should' list). Baseline 3 is appropriate when schema does the heavy lifting.

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 removes a specific section from the project main.md file, using the specific verb 'remove' with the resource 'section from project main.md file'. It distinguishes from siblings like 'update_project_section' (which modifies rather than removes) and 'delete_project' (which deletes the entire project).

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 'When to use this tool' with four specific scenarios (e.g., 'Removing deprecated or obsolete sections') and 'DO NOT use when' with three clear exclusions (e.g., 'Section contains important information'). It also implicitly distinguishes from alternatives like 'update_project_section' by emphasizing removal rather than updating.

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

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

With no annotations provided, the description carries the full burden and does so effectively. It discloses key behavioral traits: 'Permanent task removal' (destructive nature), 'Preserves other tasks' (scope limitation), 'Updates task numbering' (side effect), and 'Document why removing if significant' (audit consideration). It doesn't cover rate limits or authentication needs, but provides substantial operational context.

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

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

The description is well-structured with clear sections (purpose, when to use, key features, guidelines, exclusions, returns) and every sentence adds value. It's slightly verbose at 15 sentences, but the information density is high with minimal repetition. The structure helps with quick scanning.

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 destructive operation with no annotations and no output schema, the description provides excellent context: clear purpose, usage guidelines, behavioral transparency, and return value documentation. It covers the essential 'what, when, why, and consequences' needed for safe tool invocation. The only minor gap is lack of explicit error handling guidance beyond the return structure.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (project_id, todo_number, task_number) with their types and constraints. The description adds no specific parameter information beyond what's in the schema, but mentions 'Check task number is correct' which reinforces parameter importance. Baseline 3 is appropriate when schema does the heavy lifting.

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 specific action ('Remove a task from a TODO list'), identifies the resource ('TODO list'), and distinguishes it from sibling tools like 'delete_todo' (which removes entire lists) and 'complete_todo_task' (which marks tasks as done). The verb 'remove' is precise and differentiates from deletion operations.

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 'When to use this tool' scenarios (e.g., 'Task is no longer relevant', 'Removing duplicate tasks') and 'DO NOT use when' conditions (e.g., 'Task should be completed instead', 'Task might be needed later'). It clearly distinguishes this from alternatives like 'complete_todo_task' and addresses common decision points.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key features like case-insensitive full-text search, scope (document body, titles, content), result grouping by document, and return format details. It also provides usage recommendations (e.g., use specific keywords, try multiple terms). However, it lacks explicit mention of potential limitations like rate limits or authentication needs, which would be helpful for a 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 well-structured with clear sections (purpose, when to use, key features, usage advice, exclusions, returns). While comprehensive, it could be more front-loaded by placing the return format earlier. Some sentences in the 'You should' list are slightly redundant (e.g., points about using specific keywords and 2-3 word phrases overlap), but overall it's efficient and informative.

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

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

Given the tool's moderate complexity (search functionality with 2 parameters), no annotations, and no output schema, the description does a good job of covering behavior, usage, and return format. It explains what the tool does, when to use it, and what to expect in the response. However, it could improve by explicitly mentioning error handling or performance considerations, which would make it more complete 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 input schema has 100% description coverage, providing clear documentation for both parameters ('project_id' and 'query'). The description adds some context by mentioning 'space-separated keyword support' and advising on keyword strategies, but it doesn't significantly enhance the parameter semantics beyond what the schema already defines. This meets the baseline of 3 for high schema coverage.

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

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

The description clearly states the tool's purpose as 'Search project knowledge documents for keywords with intelligent result grouping', which is a specific verb+resource+scope combination. It distinguishes itself from sibling tools like 'get_knowledge_file' (retrieves a specific file) and 'list_chapters' (lists all chapters without search) by emphasizing search functionality across multiple documents with grouping.

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 'When to use this tool' scenarios (e.g., finding information across documents, locating technical details) and 'DO NOT use when' exclusions (e.g., when you know the exact document/chapter, need complete document listing). It also includes a 'You should' section with practical advice, offering clear guidance on when to use this tool versus alternatives like 'get_knowledge_file' for known documents.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: commits ALL uncommitted changes, pushes to remote, auto-generates commit messages, handles push failures gracefully, and forces synchronization. It also mentions operational considerations like using sparingly and checking remote configuration. The only minor gap is lack of explicit rate limit or permission requirements.

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 clear sections (purpose, when to use, key features, recommendations, exclusions, return format). Every sentence adds value—no repetition or fluff. It's front-loaded with the core purpose and efficiently organized for quick scanning.

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 (mutating synchronization operation), no annotations, and no output schema, the description provides excellent completeness. It covers purpose, usage scenarios, behavioral traits, precautions, and explicitly documents the return value structure. This compensates fully for the lack of structured metadata.

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 parameters with 100% coverage, so the baseline would be 3. The description adds value by implicitly confirming no parameters are needed ('Force... all changes'), which aligns with the schema. However, it doesn't explicitly state 'no parameters required,' which would have made it perfect.

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 specific action: 'Force git add, commit, and push all changes in the knowledge datastore.' It uses precise verbs (add, commit, push) and specifies the resource (knowledge datastore). It distinguishes itself from siblings like 'get_storage_status' by being an active synchronization tool rather than a status check.

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

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

The description provides explicit guidance with 'When to use this tool' (5 scenarios), 'You should' (5 recommendations), and 'DO NOT use when' (3 exclusions). It clearly differentiates from auto-sync and references sibling tools like 'get_storage_status' for prerequisite checks, offering comprehensive usage context.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: it preserves other chapters and document structure, updates chapter summaries, and is an efficient partial update. However, it lacks details on permissions, error handling, or rate limits, which are important for a mutation tool.

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

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

The description is well-structured with clear sections (e.g., 'When to use this tool', 'Key features', 'You should', 'DO NOT use when'), making it easy to scan. It is appropriately sized, with each sentence adding value, though it could be slightly more concise by integrating some points.

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 (a mutation tool with 5 parameters) and no annotations or output schema, the description does a good job covering usage, behavior, and exclusions. It explains the return format ({success: bool, message?: str, error?: str}), compensating for the lack of output schema, but could benefit from more detail on error cases or side effects.

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

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

The schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema, such as implying case-sensitivity for chapter_title and the .md extension requirement, but does not provide significant additional semantic context. This meets the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose: 'Update a specific chapter within a knowledge document efficiently.' It specifies the verb ('update'), resource ('chapter'), and scope ('within a knowledge document'), and distinguishes it from sibling tools like add_chapter and remove_chapter by focusing on modification rather than creation or deletion.

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

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

The description provides explicit guidance with 'When to use this tool' (e.g., correcting information, expanding content) and 'DO NOT use when' (e.g., chapter doesn't exist, need to update multiple chapters), including named alternatives like add_chapter. This clearly defines the tool's context and 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 fully discloses behavioral traits beyond the input schema. It details auto-initialization, destructive updates, git commits, and markdown validation. It also warns about impact ('Consider the impact of complete replacement') and provides actionable steps, adding significant value for a mutation tool.

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

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

The description is well-structured with clear sections (purpose, usage, features, guidelines, exclusions) and uses bullet points for readability. It is appropriately sized but could be slightly more concise by integrating some points; however, every sentence adds value, earning a high score.

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 (destructive update with auto-initialization), no annotations, and no output schema, the description provides comprehensive context. It explains behavior, usage scenarios, alternatives, precautions, and even hints at return values ('Returns: {success: bool...}'), making it complete enough 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?

The schema description coverage is 100%, so the schema already documents both parameters ('content' and 'project_id'). The description implies parameter usage (e.g., 'new markdown content' and 'project identifier') but doesn't add syntax or format details beyond the schema. This meets the baseline of 3 when schema coverage is high.

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 with specific verbs ('Create or completely replace') and resource ('main.md content for a project'). It distinguishes from sibling tools like 'update_project_section' by emphasizing complete replacement versus partial updates, making the purpose unambiguous.

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

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

The description provides explicit guidance with dedicated 'When to use this tool' and 'DO NOT use when' sections, listing specific scenarios like migrating content or creating new projects. It names alternatives (e.g., 'use update_project_section for partial changes') and includes prerequisites (e.g., 'Check if project exists first with get_project_main'), offering comprehensive usage context.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: 'Preserves all other sections intact (non-destructive),' 'More efficient than full file replacement,' 'Maintains document structure,' 'Atomic section-level updates,' and the return format. It also includes practical steps like verifying section existence and preserving formatting. However, it doesn't mention potential side effects like versioning or backup 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 well-structured with clear sections ('When to use this tool,' 'Key features,' 'You should,' 'DO NOT use when'), making it easy to scan. Each sentence adds value, such as distinguishing from sibling tools and providing actionable steps. However, it could be slightly more concise by integrating some bullet points into flowing text without losing 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 the tool's complexity (section-level updates in a file) and the absence of annotations and output schema, the description provides comprehensive context. It covers purpose, usage scenarios, behavioral traits, parameter nuances, and return values ('Returns: {success: bool, message?: str, error?: str}'). This is complete enough for an agent to understand and use the tool effectively without relying on other structured fields.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds meaningful context beyond the schema: it explains that 'section_header' must include the '## ' prefix and match exactly, and provides examples like '## Installation.' It also clarifies that 'new_content' should be without the header and advises reading current content first. This enhances understanding beyond the basic 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?

The description clearly states the tool's purpose: 'Update a specific section within the project main.md file efficiently.' It specifies the verb ('update'), resource ('section within the project main.md file'), and distinguishes it from sibling tools like 'update_project_main' by focusing on section-level updates rather than full file replacement.

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

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

The description provides explicit guidance on when to use this tool ('Modifying a single section without affecting others,' 'Adding new configuration,' etc.) and when not to use it ('Section doesn't exist (use add_project_section),' 'Need to update multiple sections,' 'Restructuring entire document'). It also names alternatives like 'add_project_section' and 'update_project_main' for different scenarios.

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