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

No annotations are provided, so the description fully discloses behavior: read-only, no modifications, server-side execution, no cloud calls or token cost, caching with instant return on subsequent calls, and path mount requirements. No contradictions.

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

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

The description is well-structured with a lead sentence, bullet-style paragraphs, and explicit Args/Returns sections. It contains necessary details without excessive verbosity. Slightly long but justified by the need to cover behavior, caching, and usage context.

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 and the presence of an output schema (Markdown report), the description covers input parameters, behavior, caching policy, usage timing, and alternative tools. It provides complete context for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 0%, but the description explains all parameters: path (absolute path in container), force (regenerate cache, default False), project (optional). It also describes the return value (Markdown report with specific sections). This compensates fully for the missing schema descriptions.

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

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

The description clearly states the tool's purpose: 'Analyze a source code directory and return a cold-start bootstrap report.' It uses a specific verb and resource, and distinguishes itself from siblings like classify_documents and write_* tools, which are mentioned for subsequent steps.

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

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

Explicit guidance is provided: 'Use at the START of work on an unfamiliar codebase instead of reading dozens of files.' It advises against frequent use of force=True and directs users to alternative tools (write_*, classify_documents) for subsequent tasks. Also notes path accessibility constraints.

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?

Declares read-only nature, scope (knowledge repo inside Docker volume), and caching behavior. No contradiction with missing annotations.

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

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

Well-structured with a clear intro line and bullet points; covers key aspects without excessive 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?

Mentions output structure and integration with execute_cleanup. Output schema covers return values. Missing prerequisites but overall adequate.

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

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

Describes the single optional parameter briefly ('Target project name (optional)'), but lacks detail on how it affects analysis. Schema has no descriptions, so description adds minimal 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?

Explicitly states 'Analyse the knowledge repo for structure issues, duplicates, and misplaced files' and distinguishes from siblings like classify_documents and check_knowledge_quality.

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

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

Provides specific when-to-use guidance: for classification use classify_documents, for simpler quality check use check_knowledge_quality, and notes that the report is cached for execute_cleanup.

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

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

The description explicitly states 'Read-only. Does not modify any files or the vector index.' This is critical behavioral info. Since no annotations are provided, the description fully bears the burden and addresses it well. It also explains return format with quality score and issue categories.

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

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

The description is well-structured with a summary, usage guidance, and parameter/return details. Every sentence is informative; no fluff. It is 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 one simple optional parameter and no required params or nested objects, the description is thorough. It explains behavioral aspects, usage context, and return format. Lacks mention of error handling or edge cases, but sufficient for a read-only validation 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?

There is one optional parameter 'project'. The schema has no description (coverage 0%), so the description's mention 'Target project name (optional)' adds meaning. However, it does not elaborate on default behavior or domain, which could be valuable.

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 'Validate the knowledge base for consistency and structural correctness' using a specific verb and resource. It distinguishes from siblings by referencing validate_doc() and get_index_stats(), providing clear differentiation.

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

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

The description explicitly advises when to use: 'Use periodically or after adding many documents to spot quality regressions.' It also gives alternatives: 'Use validate_doc() instead to check a single document before committing. Use get_index_stats() to check chunk counts rather than quality.'

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool is read-only, makes a single network request using git ls-remote, and does not modify files. However, it does not mention potential network failures or rate limits, which are minor omissions for a simple check.

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

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

The description is concise and well-structured: a clear one-line summary, followed by detailed behavioral notes in a single paragraph, and a bullet-like list of return values. Every sentence adds value without redundancy.

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

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

Given no parameters and no annotations, the description provides all necessary information: purpose, behavior, usage guidance, and return values. The presence of an output schema (as indicated by context signals) further reduces the need to describe return structure in detail.

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

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

The tool has no parameters, and schema coverage is 100% (empty). The description adds value by explaining the return format ('Up to date' message or version number with upgrade command), which is beyond the schema. Baseline for zero parameters is 4.

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

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

The description clearly states the tool checks for a newer Flaiwheel version on GitHub. It includes a specific verb ('check') and resource ('Flaiwheel version'), and distinguishes itself from sibling tools, none of which serve a similar update-checking purpose.

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

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

The description explicitly says when to use the tool: 'when you suspect Flaiwheel may be outdated, or periodically to keep the server current.' Although it does not mention when not to use it or alternatives, the context of sibling tools doesn't imply any overlapping functionality, so the guidance is sufficient.

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

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

No annotations provided, so description carries full burden. It clearly states read-only nature, explains that agent reads files locally and passes content, and that Docker container cannot access source repo. However, lacks details on rate limits, auth, or error handling.

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

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

Description is well-structured with clear sections: purpose, read-only note, trigger, step, alternative, parameter details, and return summary. Front-loaded with key info, no redundant sentences.

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 (classifying multiple files), description covers workflow, input format, output (classification, duplicates, plan), and integration with other tools. Output schema exists, so return values are adequately summarized.

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

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

Schema coverage is 0%, but description adds rich details: for 'files' parameter it explains format (JSON array of objects with path and content), recommends sending first ~2000 characters, and provides example. For 'project' it describes as optional target project name.

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: 'Classify project repo documents for migration into the knowledge base.' It also specifies it is read-only, step 1 of migration, and distinguishes from sibling tool analyze_knowledge_repo().

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

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

Explicitly provides trigger phrase ('This is the Way' or '42'), states when to use (step 1 after which write_* tools are used), and when not (use analyze_knowledge_repo() for files already in knowledge repo).

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: it moves files using git mv, creates directories, and explicitly states 'NEVER deletes any file'. It also mentions return values and a rollback command.

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

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

The description is concise at ~150 words, well-structured with clear sections, and front-loaded with the primary purpose. Each sentence provides valuable information without redundancy.

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

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

Given the simple parameter structure and presence of an output schema, the description covers prerequisites, side effects, usage patterns, and return values, making it fully informative.

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

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

Despite 0% schema description coverage, the description fully explains both parameters with examples and format: 'actions: Comma-separated action IDs... e.g. "a1,a2,a5" or "all"' and 'project: Target project name (optional)'. This adds significant meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Execute approved cleanup actions from analyze_knowledge_repo().' It specifies the verb (execute) and resource (cleanup actions), and distinguishes it from sibling tools like analyze_knowledge_repo.

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

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

The description explicitly states prerequisites ('Requires analyze_knowledge_repo() to have been called first') and follow-up steps ('Call reindex() after cleanup'), providing clear context for when and how to use the tool.

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

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

The description explicitly declares 'Read-only, no side effects,' which is a clear behavioral trait. It also describes the return values, providing full transparency without annotations. This is well above the minimum required.

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

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

The description is concise with two short sentences plus a usage notes section and return description. It is front-loaded with the core purpose and every sentence earns its place. No waste.

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

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

Given the tool's simplicity and the presence of an output schema, the description provides complete context: what it does, when to use it, alternatives, and return values. No additional information is needed.

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

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

With zero parameters and 100% schema coverage, the description adds value by explaining the return values. Baseline is 4 for zero-parameter tools, and the description enhances understanding beyond the schema.

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

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

The description clearly states the verb 'Show' and resource 'active project', and distinguishes from sibling tools by explicitly mentioning set_project() and list_projects() as alternatives for changing or listing projects. This provides a specific and differentiated purpose.

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

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

The description explicitly states when to use this tool ('to verify which project is bound before making tool calls') and directs to set_project() for changing the binding and list_projects() for viewing all projects. This provides clear when-to-use and alternative 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?

Without annotations, the description fully discloses read-only nature ('No files modified', 'Read-only'), the semantic search process, and return behavior including the 'no context found' case.

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

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

The description is well-structured with a summary, details, args section, and returns section. Every sentence is meaningful and concise, with no wasted words.

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

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

Given the presence of an output schema (mentioned in context signals), the description appropriately explains the return content and edge case, providing sufficient completeness for agent decision-making.

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

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

With 0% schema coverage, the description adds valuable context: filename is explained with examples ('payment.service.ts' or 'src/auth/jwt.py') and project is described as optional target project name.

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 'Retrieve knowledge base context relevant to a specific source file' with a specific verb and resource, and explicitly distinguishes from siblings like get_recent_sessions and search_docs.

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

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

It explicitly states when to use ('before reading or editing any source file'), when not to use ('Use search_docs() for free-form queries not tied to a specific file'), and names an alternative (get_recent_sessions).

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

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

No annotations provided, but description declares read-only, no side effects, and lists return fields. Some missing details like permissions or error handling, but sufficient.

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?

Well-structured with paragraphs and bullet points, concise with essential information. Slightly verbose in returning details, but acceptable.

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?

In context of one optional parameter and output schema, description covers purpose, usage, and return values completely.

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

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

Schema description coverage is 0%, but description adds meaning for 'project' as optional target project name. Adequate but not extensive.

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

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

Description clearly states it shows vector index statistics, is read-only, and distinguishes itself from sibling tool check_knowledge_quality.

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

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

Explicitly states when to use (check chunk counts, verify reindex, inspect config) and when not to (use check_knowledge_quality for quality issues), providing 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?

No annotations provided, but description fully discloses behavior: reads from /data/sessions-{project}.json, does not modify data, and describes output structure (timestamped entries with summary, decisions, etc.).

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

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

Concise, front-loaded with key info, no waste. Structured logically: purpose, file location, usage, parameters, return value. Every sentence adds value.

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

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

With output schema present, description explains return values sufficiently. Covers all aspects: purpose, usage, behavior, parameters, and output. No 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 has 0% coverage (no descriptions), but description fully documents both parameters: limit (default 5, max 20) and project (optional). Compensates for schema gap.

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

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

Clear verb ('retrieve'), resource ('session summaries'), and purpose ('restore context'). Explicitly notes read-only nature, distinguishing it from sibling tools like save_session_summary.

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

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

Provides explicit when-to-use: 'Call at the START of every session before any other tools' and when-to-use alternative: 'Use save_session_summary() at the END of a session to store context.' No ambiguity.

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

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

Describes the workflow (git pull then re-index only changed files), notes it's a no-op if up-to-date, and indicates what returns. Lacks explicit mention of network usage or potential side effects, but covers main 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?

Description is concise, uses bullet points for clarity, and front-loads the main purpose. Every sentence adds value.

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

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

Given the presence of an output schema, the description covers prerequisites, behavior variations, and return states. Could elaborate on project parameter usage, but overall sufficient.

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

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

The single parameter 'project' is only described as 'Target project name (optional)', which adds no meaning beyond the schema's type and default. With 0% schema coverage, the description should provide more context, e.g., how project filtering works or what default project is used.

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

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

The description clearly states the action (pull and re-index), the trigger (after pushing .md files), and distinguishes from the sibling tool 'reindex' by specifying when to use each.

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

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

Explicitly states when to call (after pushing .md files), when not to (use reindex for local writes), and mentions the prerequisite MCP_GIT_REPO_URL configuration.

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 bears the burden of behavioral disclosure. It explicitly declares 'Read-only', which is the key behavioral trait for a list operation. It also describes the return value in detail, including the per-project summary and the empty state behavior. No side effects or auth requirements are mentioned, but for a read-only list, this is adequate.

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

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

The description is concise and well-structured: a single sentence stating the core functionality, then a 'Use to' section, and a 'Returns' section. Every sentence adds value, with no redundancy or unnecessary detail. It is front-loaded with the main purpose.

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

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

Given zero parameters, no annotations, and the presence of an output schema, the description is complete. It explains the output per project (name, chunks, quality score, docs path, git repo URL) and the behavior when no projects are registered. No gaps remain for an agent to effectively use this 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?

The input schema has zero parameters, and schema description coverage is 100% vacuously. The description adds no parameter-specific information, but with no parameters to describe, a baseline score of 4 is appropriate as the description compensates by explaining the output.

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

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

The description uses the specific verb 'list' and the resource 'projects', clearly stating it lists all registered projects with chunk counts and health stats. It distinguishes itself from the sibling tool 'get_active_project' by noting that the latter checks only the active project, 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 explicitly states when to use the tool ('to check which projects exist...') and provides a clear alternative ('Use get_active_project() to check only the active project'). It also mentions the behavior for empty projects. While it could include explicit 'when not to use' guidance, the context is sufficient for an agent.

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

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

Describes in-place modification, no source file changes, diff-aware default, and force rebuild behavior. Mentions stale chunk removal but lacks potential side effects or auth details. With no annotations, description carries full burden and does well.

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

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

Well-structured with intro, bullet points, and returns section. Not overly verbose, but could be slightly more compact.

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

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

Covers purpose, behavior, parameters, and return values. Output schema exists but description's Returns section is sufficient. No missing information for a reindex 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 coverage is 0%, so description compensates fully. Explains force parameter (purpose and when to use) and project parameter (target project). Adds meaning beyond schema defaults and types.

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

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

The description clearly states 'Re-index the knowledge base docs into the vector store' with specific verb and resource. It distinguishes from sibling tool git_pull_reindex by noting its better fit for git-push changes.

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

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

Explicitly advises when to use force=True (after changing embedding model) and when to prefer git_pull_reindex (for git-sourced changes). Provides clear default behavior (diff-aware).

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

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

With no annotations, the description fully discloses behavior: read-only, lists recognized relation keys, explains output format (Markdown with truncation and not-found hints), and describes how relations are declared in frontmatter. This exceeds expectations.

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

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

The description is well-structured with a summary first, then a YAML example, recognized keys, args, and returns. It's longer but each part adds value. Minor conciseness issues: the example could be shorter, but overall front-loading is effective.

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 and that an output schema exists, the description is complete: it explains behavior, truncation, not-found hints, recognized keys, and references an alternative tool. No gaps in context.

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

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

Schema description coverage is 0%, but the description explains entity_id as the frontmatter 'id' value and project as an optional target project name, adding meaning beyond schema types and defaults. It could be more explicit about project's role, but it's good.

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 returns structured relations for an entity from YAML frontmatter, uses specific verbs like 'Return structured relations', and distinguishes from siblings like timeline() by mentioning it as an alternative for change history. It lists recognized relation keys, 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 clear context on when to use (to resolve an entity's relations) and explicitly suggests timeline() for change history. However, it does not explicitly state when not to use this tool or provide alternatives for tasks like listing all entities or searching, but the context is sufficient for most agents.

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

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

Discloses side effects (appends to JSON file, does not modify vector index or knowledge repo), states it is safe to call multiple times, and explains each call adds a new entry. No annotations were provided, so the description fully carries the burden.

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

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

Well-structured with clear sections: main purpose, side effects, usage, arguments, returns. Every sentence adds value, and the information is front-loaded. Despite length, it is appropriately concise for the detail needed.

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

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

Covers all necessary aspects: what the tool does, side effects, when to use, parameter details, and return value. With no annotations and a low schema coverage, the description provides complete context for correct agent usage.

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

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

The description includes an Args section that explains each parameter's purpose (e.g., summary: 1–3 sentences, decisions: comma-separated, optional). The schema only has types and defaults, so the description adds significant meaning.

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

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

The description clearly states the tool appends a session summary to the project's session log, using a specific verb and resource. It distinguishes itself from sibling tools like get_recent_sessions by explaining the complementary usage.

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

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

Explicitly instructs to call at the END of every session and to use get_recent_sessions at the start of the next session, providing clear when-to-use guidance with an alternative tool.

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

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

Since no annotations are provided, the description fully discloses behavior: it is read-only with no side effects, returns ranked chunks with specific fields, and prompts a follow-up action. This meets the high bar for transparency.

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

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

The description is well-organized with sections (purpose, usage, Args, Returns) and every sentence adds value. No redundancy; it is appropriately concise for the information conveyed.

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

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

Given the tool's complexity (3 params, simple return schema), the description covers purpose, usage, parameters, return format, and follow-up actions. No gaps identified.

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

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

With 0% schema description coverage, the description adds meaning to all three parameters: query is 'Description of the current problem or error message', top_k has a default, and project is optional. This compensates fully for the schema gap.

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

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

The description clearly states 'Search only bugfix summaries for similar past problems', providing a specific verb and resource. It also distinguishes from the sibling tool search_docs by noting its focused scope.

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

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

Explicit guidance is given: prefer this over search_docs when debugging, and use search_docs for broader queries. Also instructs to call write_bugfix_summary when no matches are found.

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

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

With no annotations provided, the description carries the full burden. It states 'Read-only, no side effects' and describes the return value as 'Ranked chunks... with source, relevance %, and text.' It does not detail error conditions or rate limits, but the core behavioral traits are well-covered.

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

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

The description is a single paragraph but well-organized: opening summary, usage instructions, then a clear parameter list. Every sentence is informative and concise. No wasted words.

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

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

Given the tool complexity (4 parameters, filtering, no annotations, has output schema), the description covers purpose, usage, parameters, and return value comprehensively. It mentions output format and differentiates from siblings. No critical information is missing.

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

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

Schema description coverage is 0%, so the description must fully explain parameters. It does: query is 'Search query (natural language)', doc_type lists all allowed values, top_k explains default 5, and project is 'Target project name (optional)'. This adds meaning far beyond the bare schema.

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

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

The description clearly states the tool searches documents filtered by a specific category ('Search filtered by a specific document category') and explicitly notes it is read-only with no side effects. It distinguishes itself from sibling tools like search_docs, search_bugfixes, and search_tests by describing when to use each.

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: 'Use instead of search_docs() when you know the category' and mentions alternatives: 'Use search_bugfixes() or search_tests() as convenient shortcuts for those specific categories.' This clearly tells the agent when to use this tool vs others.

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

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

With no annotations, the description fully discloses behavior: read-only, no side effects, and describes the return format including how 'no results' is handled with a rephrasing suggestion.

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?

Well-structured with clear sections: purpose, usage guidelines, args, returns. Every sentence is concise and contributes value, no redundancy.

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

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

Despite an output schema existing, the description covers all necessary context: purpose, usage rules, parameter semantics, and return details including edge cases. Complete for a search 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 has 0% description coverage, but the description explains each parameter: query as natural language, top_k with default and usage advice, and project as optional with default behavior, adding significant meaning.

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

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

The description clearly states 'Semantic search over the ENTIRE project knowledge base' with 'Read-only, no side effects', distinguishing it from sibling tools like search_bugfixes, search_by_type, and search_tests.

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

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

Explicitly advises 'Use this ALWAYS before writing or changing code' and provides clear alternatives: 'Prefer search_bugfixes() when debugging...', 'Use search_by_type() when you know the category.', 'Use search_tests() when looking for test coverage.'

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

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

With no annotations, the description transparently discloses it is read-only with no side effects. It describes return fields and signals when to call write_test_case, though lacks details on pagination or error handling.

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 for purpose, usage, args, and returns. It is informative but could be slightly more concise; the bullet-like args section is clear.

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 (3 parameters, output schema exists), the description covers purpose, usage, behavior, parameters, and return values thoroughly without relying on 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?

The input schema has 0% description coverage, but the description fully compensates by defining each parameter with examples and defaults, adding meaning beyond the schema.

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

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

The description clearly states the tool searches test documents and is read-only. It distinguishes itself from the sibling 'search_by_type' by noting it is more intent-clear for test-coverage workflows.

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

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

Explicitly advises calling this tool before write_test_case() to avoid duplicates. References an alternative (search_by_type) and clarifies when this tool should be used.

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

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

No annotations provided, but description fully discloses in-memory only, no file modification, per-connection binding, and return value details for success and failure.

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?

Well-structured with bullet points, front-loaded with primary purpose, no wasted words. Every sentence adds value.

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

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

Single parameter with output schema; description explains purpose, usage pattern, return values, error handling, and differentiates from many sibling tools.

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

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

Schema has 0% description coverage, but description adds that 'name' must be a registered project from list_projects(), providing essential context beyond the schema.

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

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

Description clearly states it binds all subsequent tool calls to a specific project, and distinguishes from sibling tools setup_project (create new) and get_active_project (check binding).

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

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

Explicitly instructs to call at the START of every session, and explains when to use setup_project or get_active_project instead. Also clarifies override behavior with project= parameter.

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

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

No annotations provided, so description carries full burden. It lists side effects: creates directory, optionally clones git, runs index, binds session. Notes idempotent. Missing details like synchronous vs async index, but sufficient for transparency.

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

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

Well-structured: summary, side-effects, usage guidance, Args, Returns. Front-loaded with key info. Returns section slightly vague ('Project name, chunk count...') but overall concise and efficient.

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

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

Given complexity (6 params, mutation with side effects, output schema exists), the description covers all essential aspects: behavior, all parameters, returns, and distinguishes from siblings. No gaps identified.

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

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

Schema has 0% description coverage, so description must compensate. It provides full Args section explaining each parameter: name (short identifier, no spaces), git_repo_url (HTTPS, optional), git_branch (default main), display_name (optional label), git_auto_push (default true), git_sync_interval (default 300s). Adds significant meaning beyond schema 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 'Register and initialise a new project in Flaiwheel.' It specifies the verb (register/initialize), resource (project), and scope (new project). It distinguishes from siblings like set_project (switch) and list_projects (list).

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

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

Explicit guidance: 'Call once per project. Use set_project() to switch between already registered projects. Use list_projects() to see what exists.' Also notes idempotency, so safe to call again if exists.

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

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

The description details the read-only nature, the resolution logic, git log execution, return format, and error hints (empty result for non-git checkout). It adds substantial behavioral context beyond annotations (none provided).

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

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

The description is concise with a clear summary, structured Args/Returns sections, and each sentence adds value. No wasted words.

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

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

Given the output schema exists, the description covers the return format and error cases. It explains the tool's purpose, parameters, and behavior comprehensively.

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

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

Schema coverage is 0%, but the description explains all three parameters: entity_id (frontmatter id), limit (max commits, default 20, max 200), and project (optional). This adds meaning beyond the bare schema.

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

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

The description clearly states the tool returns git history for a document, using a specific verb (Return) and resource (git history of the document). It distinguishes from siblings by focusing on historical timeline, unlike search or write 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 explicitly provides a use case: 'Use this to answer "what was true at time T?"' and explains why git history is used. It does not explicitly mention when not to use or name alternatives, but the context is clear.

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?

Declares read-only behavior and explicitly states it does not write files or modify the index. This is beyond what annotations (none) provide, giving full transparency.

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

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

Well-structured with a summary line, guidance section, parameter list, and return value. Slightly verbose but every sentence is 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 complexity and having an output schema, the description covers purpose, usage, parameters, and return values completely. No gaps in essential information.

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

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

Despite 0% schema coverage, the description explains all three parameters: content as full markdown, category with a list of valid values, and project as optional name. This adds significant meaning beyond the schema.

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

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

The description clearly states the tool validates a markdown document before committing it to the knowledge repo, distinguishing it from sibling tools like write_* that validate internally. The verb 'validate' and resource 'markdown document' are specific.

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

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

Explicitly states when to use (manual git commit) and when not (when using write_* tools), and names alternatives. This provides clear guidance on tool selection.

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

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

With no annotations, the description carries the full burden and discloses key side effects: overwrites existing files, indexes into vector store, and auto-pushes to git. It also describes return values. However, it could mention potential failure modes for auto-push or permission requirements, but overall it is transparent given the 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 structured with clear sections: main purpose, side effects, usage guidelines, parameter list, and returns. It is front-loaded with the most critical information and every sentence adds value with no redundancy.

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

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

Given the 8 parameters (5 required) and no annotations, the description provides sufficient context for an agent to select the tool and fill parameters correctly. It covers side effects, alternatives, and return format, and the presence of an output schema further reduces the need to describe return values in detail.

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

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

Schema description coverage is 0%, so the description must compensate. It provides natural-language explanations for all 8 parameters (e.g., 'Short title', 'URL path', 'HTTP method'), adding meaning beyond the schema's type definitions. Though thorough, it could clarify the format for request_schema and response_schema more precisely.

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

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

The description clearly states 'Create an API endpoint document, index it, and auto-push to git,' specifying the verb, resource, and actions. It also distinguishes from siblings by naming alternatives: write_architecture_doc for system-level decisions and write_best_practice for API coding conventions.

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

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

Explicitly says 'Use for HTTP endpoints, REST APIs, and RPC schemas' and provides alternatives for other document types, giving clear guidance on 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?

Discloses side effects (file creation, indexing, git push, overwrite behavior). Without annotations, this provides substantial transparency, though could mention permission requirements or failure modes.

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?

Well-structured with summary, bullet-like side effects, usage guidance, and parameter list. Every sentence adds value, though slightly verbose for the parameter descriptions.

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

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

Covers all key aspects: purpose, side effects, usage, alternatives, parameters, and return values. Suitable for a complex tool with 7 parameters and missing 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?

With 0% schema coverage, the description adds value by explaining each parameter's purpose (e.g., 'decisions: Key architectural decisions made and why'). Provides enough context for correct usage, though lacks examples or formats.

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

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

Clearly states the tool creates architecture documents, indexes, and auto-pushes. Explicitly differentiates from siblings by naming alternative tools for other doc types.

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

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

Explicitly states when to use (system design, ADRs, component relationships) and when not to use by referencing siblings like write_api_doc, write_best_practice, write_bugfix_summary.

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

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

No annotations are provided, so the description carries full burden. It discloses side effects (creates file, indexes, pushes to git, overwrites existing). However, it omits details about authorization needs, error handling, or what happens if auto-push fails.

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

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

The description is well-structured with a summary, side effects, usage guidelines, and args list. It is concise but could be slightly tighter (e.g., 'Args:' could be merged with the preceding list). Overall, every sentence adds value.

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

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

Given 6 parameters (4 required), the presence of an output schema, and no nested objects, the description covers purpose, side effects, usage, and args. It lacks details on input format specifics (e.g., is markdown expected?) but is otherwise complete for an agent to use the tool effectively.

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

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

The schema has no descriptions for any parameters (0% coverage). The description compensates by explaining each parameter in plain English: title, context, rule, rationale, examples, project. This adds semantic meaning beyond the schema's type/title information.

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

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

The description uses a specific verb-resource combination: 'Create a coding standard or best practice document, index it, and auto-push.' It clearly identifies the tool's purpose and distinguishes it from sibling tools like write_architecture_doc and write_bugfix_summary.

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

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

The description explicitly states when to use this tool ('Use for recurring patterns, conventions, and rules the team should follow') and provides concrete alternatives for other scenarios ('Use write_architecture_doc() for system-level decisions, write_bugfix_summary() after fixing a specific bug').

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?

Annotations are not provided, but the description details all side effects: creates file in bugfix-log/, indexes into vector store, pushes to remote git, and overwrites if same title same day. Discloses dependencies on MCP_GIT_REPO_URL. No contradictions.

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

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

The description is front-loaded with the core action and mandatory status. It includes side effects, alternatives, and parameter details. While slightly long, every sentence adds value, so it's 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?

The tool has 7 parameters (4 required) and no output schema annotations, but the description covers the return format ('Saved filename, chunk count, and whether auto-push succeeded'). Combined with behavioral and usage details, it is fully complete for an agent to invoke correctly.

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

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

Schema description coverage is 0%, but the description includes an Args section with meaningful explanations for each parameter (e.g., title used in filename, root_cause: 'be technical', solution: 'describe code changes'). This adds significant value beyond the schema.

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

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

The description explicitly states 'Create a bugfix summary .md file, index it immediately, and auto-push to git.' It clearly specifies the verb (create) and resource (bugfix summary file), and differentiates from siblings like write_architecture_doc and write_best_practice.

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 declares 'MANDATORY after every bug fix' and provides explicit alternatives: 'Use write_architecture_doc() for design decisions, write_best_practice() for recurring patterns.' This gives clear when-to-use and when-not-to-use guidance.

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

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

With no annotations, the description fully discloses side effects: file creation, vector store indexing, git push, idempotency (overwrites on same version), and error conditions. This provides clear behavioral expectations.

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

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

The description is well-structured with a summary line, bullet points, and arg list. It is concise but contains minor redundancy (error condition mentioned twice). Still, every sentence adds value.

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

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

Given the complexity (7 parameters, output schema present), the description covers the tool's purpose, side effects, usage, parameters, and return value format. It is sufficiently complete for an agent to invoke correctly.

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

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

Schema coverage is 0%, but the description provides detailed explanations for all 7 parameters, including format examples (e.g., '2.1.0' for version) and semantic meaning of optional content fields. This adds significant value beyond the schema.

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

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

The description clearly states the verb 'Create a changelog entry for a release, index it, and auto-push to git,' identifying specific resource and actions. It distinguishes from sibling write_* tools by focusing on changelog entries.

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

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

The description explicitly says 'Use for release notes and version history' and specifies the precondition that at least one content field must be provided. However, it does not mention when not to use or compare with alternatives.

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

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

With no annotations, the description details side effects (creates file, indexes, auto-push) and overwrites existing files. It mentions return values but lacks specifics on permissions or failure modes, which is a minor gap.

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

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

The description is well-structured with headers for side effects, usage, args, and returns. It is slightly long but every sentence adds value; could be slightly 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?

Given 6 parameters, side effects, return value, and sibling tools, the description covers all essential aspects: purpose, usage, parameter meanings, return format, and relationship to alternatives.

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

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

Despite 0% schema description coverage, the description provides an Args section explaining all six parameters (title, prerequisites, steps, verification, troubleshooting, project) with clear roles and format suggestions.

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 setup, deployment, or infrastructure document, with specific verbs and resource (create, index, auto-push). It distinguishes from sibling write_architecture_doc by naming it directly.

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

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

Explicitly lists use cases (environment setup, CI/CD, Docker, deployment runbooks) and directs to use write_architecture_doc for system design, providing clear when-to-use and when-not-to-use guidance.

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

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

Discloses side effects: file creation with specific naming, vector store indexing, and git push. No annotations provided, so description carries full burden; it fully informs the agent of all behavioral impacts.

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?

Well-structured with sections (purpose, usage, side effects, args, returns), but contains minor redundancy (status values mentioned twice). Still efficient and easy to parse.

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 (9 parameters, side effects, output), the description fully covers all aspects. Output schema exists and return values are described. No gaps remain.

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

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

Schema has 0% description coverage, but the description explains all 9 parameters, including defaults, status enum values, and optional nature. Adds significant meaning beyond schema types/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?

Clearly states the tool creates a test case document, indexes it, and auto-pushes to git. Distinct from sibling write tools (e.g., write_api_doc) by specifying test case creation and its unique side effects.

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

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

Explicitly advises calling search_tests() first to check coverage, and states the tool should be used after writing or modifying tests. Provides clear when-to-use context and implies alternatives (search_tests).

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