Zephex

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable behavioral details: probe_engine fallback behavior ('gracefully falls back to fetch with probe_fallback_warning'), scan timing differences (quick vs deep), rate limit ('one scan per hostname per 5 seconds'), and constraints on ports and IPs. No contradictions with annotations.

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

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

The description is comprehensive but verbose, spanning multiple paragraphs with extensive enumeration of return fields and edge cases. While well-structured (overview, usage, returns, limits), it could be more concise by moving some detail to 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?

With no output schema, the description thoroughly documents return structure (product, duration_ms, summary, health, tech, secrets, network, issues, ssl, etc.), covers all parameter behaviors, and addresses limitations, rate limits, and fallback logic. This compensates fully for the lack of output schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by clarifying scan_depth modes ('quick=light scan, 3 bundles; deep=full supply URL phase with JWT decode, source maps, verification ~8-12s') and probe_engine fallback. However, some parameter details (like default values) are already in the schema.

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

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

The description begins with a clear, specific statement: 'Site Audit — full HTTP intelligence for a public URL in one call.' It enumerates core capabilities (security grade, health, tech stack, secrets, timing) and distinctly separates this tool from siblings like `check_package` or `read_code`, which focus on code analysis.

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 lists concrete call scenarios: 'CALL when: user pastes a URL; post-deploy security check; cert expiry or HSTS/CSP questions; ...' It also states limitations (public hostnames only, blocks localhost/private IPs, rate limiting), 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?

Annotations include readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description explicitly ends with 'Read-only', consistent with the annotation. The description adds behavioral context: 'Each task returns focus, summary, data, hint, related_tasks, next_calls, meta' and explains version resolution via GitHub API. No contradiction.

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 dense but well-structured: it opens with the main purpose, then lists tasks, use cases, workflow, and exclusions. At ~150 words, it is somewhat verbose but efficiently packs essential details. Front loading is good.

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 8 parameters and no output schema, the description thoroughly explains return fields per task, version resolution, workflow steps, and ecosystem support. It covers all necessary context for an AI agent to correctly invoke the tool.

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

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

Schema coverage is 100% with descriptions for all 8 parameters. The description adds context beyond the schema, such as explaining the 'source' parameter's behaviors (github:owner/repo vs local) and the workflow for 'from_version' and 'version'. While the schema already does a good job, the description enriches 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: 'Verify any package on live registries before install — and plan upgrades from GitHub release notes.' It lists five specific tasks (check, upgrade, security, migrate, debug) and explicitly distinguishes from sibling tools like get_project_context and project_memory via a 'DO NOT use' 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?

The description provides explicit when-to-use scenarios (frameworks, payments, auth, databases, any dep) and when-not-to-use (repo orientation, lockfile audit, API docs, install verification). It also provides a concrete workflow example: get_project_context → check_package → task=security → task=upgrade.

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?

Description adds extensive behavioral context beyond annotations: caching behavior, credit costs, path requirements, diff_base usage, and scope to modules. No contradiction with annotations.

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

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

Well-structured with bullet points and clear sections. Slightly verbose but front-loaded with main action. 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?

Fully covers all aspects: 16 params described, workflows, cost, exclusion list, output details (even though no output schema). Complete for a complex 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 100%. Description adds extra meaning on parameters like diff_base for patch coverage, task enum meanings, and path format. Adds value beyond schema.

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

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

Clearly states it runs tests and returns structured health. Explicitly differentiates from siblings by listing when NOT to call, like check_package, project_memory, etc. Specific verb+resource.

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 detailed when-to-use (after code changes, before push, user asks if tests pass) and when-not-to-use (with explicit sibling names). Includes workflow instructions (task=run once then session tasks) and credit costs.

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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral details like modes (overview, deep, audit) and cache bypass behavior via the force parameter, which goes beyond annotations. However, no mention of rate limits or other potential constraints.

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 purpose and uses structured phrases, but it is lengthy with some redundancy (e.g., explaining path and subpath separately). It could be more concise while retaining essential information.

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

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

Given the tool's complexity (12 parameters, no output schema), the description covers usage context, parameter behavior, return types (concern_cluster, layer_map, etc.), and mode differences. It compensates well for the missing output schema and provides complete guidance 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 coverage is 100%, but the description adds significant value by explaining key parameters (concern, seed_files, mode, focus) and their interactions—e.g., 'seeds via concept search + import graph, not hardcoded vocab' and the relationship between concern and seed_files. This enriches 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 tool's purpose: 'Structural wiring map — how files connect, not file bodies.' It specifies the outputs (concern_cluster, layer_map, entry_points, etc.) and distinguishes itself from siblings like read_code and find_code by emphasizing it does not return file bodies.

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 guidance: 'CALL WHEN: how does this feature/subsystem work across files before a cross-cutting edit' and 'DO NOT: stack/scripts (get_project_context), search (find_code), read bodies (read_code).' It also explains how to pass concern or seed_files from find_code, 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's 'Read-only' confirmation is redundant but consistent. However, the description adds valuable behavioral context about response structure, next steps, and edge cases (e.g., whole_word behavior for renames), which goes beyond 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 somewhat lengthy but every sentence serves a purpose. It is front-loaded with the core purpose and then systematically covers use cases, parameters, and response. It could be slightly more concise by reducing redundancy (e.g., 'Read-only' is already in annotations), but overall it is well-organized.

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

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

Despite having no output schema, the description compensates by explaining the response format (summary, data.matches or data.all_occurrences, files_hit, next_calls) and linking to the next step (read_code). It covers all major use cases and edge cases, making the tool fully understandable for an AI agent.

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

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

With 100% schema coverage, the schema already documents all 10 parameters. The description adds significant meaning by providing concrete examples for each parameter, explaining enum options, and clarifying usage context (e.g., 'also_try: extra keywords merged in parallel'). This greatly aids correct invocation.

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

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

The description starts with 'Find text inside project files (ripgrep)' which is a clear verb+resource. It further distinguishes from sibling tools like read_code and get_project_context by specifying that it is for searching text, not for reading known files or overview.

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 covers when to use the tool (rename, pasted line, symbol, topic, messy repo) and when not to use it ('Not for known-file reads or repo overview'). It also provides specific patterns for each use case (e.g., 'Pasted line → snippet').

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 already indicate read-only and idempotent. Description adds context about caching, re-detection, and filesystem access (local vs remote). No contradictions. Fully discloses behavior beyond 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?

Description is well-structured: brief summary first, then topics, sources, workflow, exclusions. Every sentence adds value. No fluff. Appropriately detailed without being verbose.

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

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

Given 8 parameters, no output schema, and high complexity, the description is complete. It covers all parameters, provides workflow, sources, and exclusion criteria. Leaves no gaps for a read-only exploration 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 100%, but description adds significant value: examples for path, enumerates all 11 topics, explains inline_files shape, and provides usage recommendations (e.g., start with identity). Goes well beyond schema.

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

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

The description explicitly states the tool's purpose: orient on a codebase before editing. It distinguishes itself from siblings by listing specific alternatives (read_code, find_code, explain_architecture). Includes specific verb+resource and 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?

Provides explicit when-to-use (before editing), a workflow (call identity first then related_topics), and when-not-to-use (function bodies, search, flows). Also explains different source types and their behaviors.

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?

Adds significant behavioral details beyond annotations: return values (shouldContinue, riskLevel, repetitionWarning, etc.), loop detection mechanics, hard cap of 10 thoughts, checkpoint writing on session close. No annotation contradiction.

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 (returns, call when, do not call, parameter usage). Comprehensive but slightly verbose; could trim redundant phrases. Front-loaded with key purpose and distinction.

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 13 parameters, 6 required, no output schema, the description covers return values, behavioral constraints (loop detection, cap), and usage patterns comprehensively. Everything an agent needs to invoke the tool correctly.

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

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

All 13 parameters have schema descriptions (100% coverage). The description adds contextual usage tips (e.g., 'Pass lastActions to enable boredom detection', 'Set actionReady:true to exit early'), enhancing practical 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 is a multi-call reasoning scaffold for tracking hypotheses, observations, conclusions, and assumptions. It explicitly distinguishes itself from Anthropic's think tool and extended thinking, establishing a unique 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?

Provides explicit 'Call when' and 'DO NOT call when' sections with concrete scenarios (e.g., high-blast-radius edits, debugging after 2+ failed attempts, single-step tasks). Clearly delineates when to use vs. when to act directly.

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?

Description lists return shapes and constraints (max 200, FTS5 max 5 hits), but annotations indicate readOnlyHint=true while tool includes write actions (remember, forget), contradicting the annotation. Without annotations, description would score higher, but contradiction reduces 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?

Description is well-structured with sections: purpose, exclusions, returns, call guidelines, constraints. Slightly lengthy but every sentence adds value. Front-loaded with 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?

Given 12 parameters, no output schema, and 100% schema coverage, the description explains actions and return structures. Includes integration notes (local stdio). Missing some edge-case details but overall comprehensive.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds usage context and highlights key parameters (action, query, title) but does not provide significant additional 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?

Description clearly states verb+resource: 'Store and recall project-specific learned facts'. Explicitly distinguishes from sibling tool 'get_project_context' by stating what it is NOT for.

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-call and when-not-to-call scenarios, including alternatives: use get_project_context for repo orientation, find_code for symbol search, read_code for file bodies. Also gives post-recall instructions and constraints like max 200 per project.

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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by disclosing the 'Read-only' nature, the surgical/truncated behavior, and the return envelope structure. No contradictions found. Score 4 as it goes beyond annotations but could note error handling or rate limits.

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

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

The description is extremely concise and front-loaded. It uses brief, scannable sections ('CALL WHEN', 'DO NOT') and every sentence adds value. No fluff.

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

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

The description gives a comprehensive overview of the tool's functionality and usage, covering all modes and when to invoke them. However, given the complexity (17 parameters, no output schema), it does not detail all parameters (schema covers them) or fully describe the output format beyond mentioning the envelope fields. Still, it is sufficiently 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?

Schema coverage is 100%, so baseline is 3. The description does not repeat parameter details but adds contextual usage guidance (e.g., which mode for which scenario). This complements the schema without adding new parameter-level meaning.

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

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

The description clearly states the tool's purpose as a 'Surgical code read' for reading code in various modes (file, symbol, scan, smell, outline). It explicitly contrasts with the sibling tool find_code for whole-repo search, and uses specific verbs and resources.

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 'CALL WHEN' and 'DO NOT' sections, detailing when to use this tool (path known from find_code, batch read files, extract symbols, etc.) and when to use alternatives (find_code for unknown location, editor Read for files < 50 lines).

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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description reinforces this by describing a knowledge retrieval workflow and adds the context that it covers many domains. No contradictions.

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

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

The description is a single paragraph that front-loads the purpose. It packs relevant information efficiently, though it could be slightly more concise by removing redundant phrases like 'Expert developer knowledge base' after the title.

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 (4 parameters, no output schema, rich annotations), the description fully explains what the tool does, how to use it, and what it covers. The workflow instructions make it complete for agent invocation.

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

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

Schema coverage is 100% with clear descriptions. The description adds operational semantics by explaining the search-then-get workflow, which adds value beyond the schema's individual parameter 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 it is a 'developer knowledge base' for building, structuring, securing, and deploying. It explicitly mentions two operations ('search' and 'get') and lists covered domains. This distinguishes it from sibling tools and gives a specific verb-resource pair.

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

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

The description gives clear usage guidance: 'Always search first, then get.' It also says to use when the user asks about specific topics. It doesn't explicitly state when not to use, but the context implies it's for developer questions only.

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