Zephex

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

Discloses read-only nature, blocks localhost/private IPs, credit cost, and timing differences between quick/deep scans. Annotations already indicate readOnlyHint, but description adds valuable context like credit usage and timeout guidance.

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?

Reasonably concise with front-loaded purpose and example. Could be slightly trimmed, but each sentence adds value. Structure is logical: purpose, usage, example, exclusions.

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 output types (grade A-F, health statuses), timing, and exclusions. Lacks detailed output schema but given no output schema, the description provides sufficient context for an agent to understand what the tool returns.

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 covers all 18 parameters with descriptions (100% coverage). Description adds usage hints (e.g., 'include_fix_snippets token-heavy') and an example, but mostly restates schema info. Adds moderate 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?

Clear verb 'audit' with specific resource 'public HTTPS URL' and outputs like security grade, SSL, headers, etc. Explicitly distinguishes from sibling tools by listing what it is NOT for (find_code, check_package, etc.).

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?

States when to use: 'Call when user pastes a live URL — post-deploy check' and explicitly lists alternatives for other use cases. Also recommends reading plain_summary first.

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, destruptiveHint=false. The description goes beyond by noting that no project path is needed (just package name + version), that credits are consumed (5 hosted), and that internal fields (channel, cli_depth) should be omitted by agents. It also describes the return structure (summary, data, next_calls, meta.credits). 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 well-structured: core purpose first, then tasks, then usage guidance, then exclusions, then example. It is relatively long but every sentence adds value, including the explicit listing of not-for scenarios. Could be slightly shorter by merging some list items, but overall efficient for the 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 8 parameters, multiple task types, and no output schema, the description covers all necessary aspects: purpose, tasks, parameter explanations, when-to-use, when-not-to-use, example, and return field hints (summary, data, next_calls, meta.credits). The high schema coverage and annotations complement the description, making it fully complete.

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

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

Schema coverage is 100% (all 8 parameters documented with descriptions). The description adds further meaning: for task, it details each enum value's purpose (check: exists/slopsquat/deprecation/CVEs; upgrade/migrate: breaking_changes+migration_steps; security: CVEs for your version). For version and from_version, it clarifies their required contexts. The examples (package: 'next', task: 'upgrade') add practical clarity.

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

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

The description clearly states that the tool checks a public registry package before install or version bump, listing specific frameworks (next, react, vite), payments (stripe), auth (next-auth, clerk), ORMs (prisma, drizzle). It enumerates tasks (check, upgrade, migrate, security) and their purposes, distinguishing it from sibling tools like get_project_context, find_code, etc., with explicit 'NOT for' exclusions.

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 ('Call BEFORE npm install or bumping next/stripe/prisma') and when not to use it ('NOT for repo layout (get_project_context), import search (find_code), tests (check_test), architecture (explain_architecture), live URLs (audit_headers)'). It also provides an example call with parameters, giving clear context for 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?

Discloses extensive behavioral traits beyond annotations: non-destructive ('Does not modify source'), credit system for each task, caching behavior for session tasks, billing indicators (meta.credits), scope of task=missing (git diff scan), and detail_level token budgets. No contradiction with annotations.

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

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

The description is long but well-structured and front-loaded with the core purpose, then workflow, billing, usage guidance, and examples. Every sentence adds value, though it could be slightly more terse. Length is justified by tool complexity (17 parameters, multiple tasks).

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 absence of an output schema and high parameter count, the description is comprehensive. It covers local vs hosted modes, credit costs, workflow examples, and credit monitoring. No obvious gaps for an AI agent to misuse 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?

While schema description coverage is 100%, the description adds meaningful context: explains credit implications for each task, when parameters like path or session_id are required, how diff_base is used, and the purpose of area and inline_files. Examples illustrate parameter combinations.

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 runs tests and returns structured health data (fix_first, broken_areas, etc.). It explicitly distinguishes from siblings like find_code, audit_headers, check_package, and get_project_context. The verb+resource+scope pattern is precise.

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

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

Provides explicit when-to-use guidance: 'Call after every substantive edit, when user asks if tests pass or if tests are missing, or before push.' Also specifies when-not-to-use with a list of alternative tools and gives a detailed workflow example with tasks, credits, and diff_base usage.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds caching behavior, cost, auto-degrade for large repos, and confirms read-only nature.

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?

Dense but no wasted sentences; front-loaded with purpose. Slightly verbose but each sentence adds value.

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

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

Thorough given 12 params, annotations, no output schema. Covers envelope, meta, data outputs, token estimates, and usage scenarios.

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

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

Schema coverage is 100%. Description adds context beyond schema: explains concern usage, seed_files, inline_files fallback. Slightly above baseline.

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 'Maps how files connect across a subsystem — roles and import edges, not file bodies.' Distinguishes from siblings by explicitly listing what not to use.

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 'Call BEFORE cross-cutting edits' and lists alternatives: 'Do NOT for stack (get_project_context), search (find_code), bodies (read_code)...'.

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, but the description adds concrete behavioral details: token-capped vs raw grep, read-only nature, and envelope response structure. No contradiction with annotations.

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

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

The description is somewhat lengthy but well-structured and front-loaded with the key preference and summary. Every sentence adds value, though minor trimming could improve conciseness without loss.

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 10 parameters, no output schema, and sibling tools, the description covers usage context, parameter details, output structure (envelope fields), and clear don't-use cases. It is fully complete for an AI agent to decide and invoke correctly.

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

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

Schema coverage is 100%, yet the description adds significant meaning: explains intent values with examples (snippet=pasted line, symbol=known name), path format differences between local and hosted, and the purpose of include options. This goes well 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 finds code using ripgrep + AST ranking, and distinguishes itself from sister tools by naming specific alternatives (read_code, get_project_context, etc.). The verb 'find' and resource 'code' are specific, and the scope is well-defined.

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

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

The description explicitly says when to use ('PREFER over native Grep when location is unknown', 'Call when: where is X, usages, rename prep') and when not to use ('DO NOT: known symbol+file (read_code), stack/scripts (get_project_context), wiring (explain_architecture), tests (check_test), packages (check_package), URL audit (audit_headers)'). Alternatives are named for each exclusion.

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 details beyond annotations: 'Secret-sanitized', '7 credits hosted', response structure (topic, focus, summary, data.key_paths, hint, related_topics, next_calls, meta.credits), 'force:true refreshes cache', and 'Read-only'. No contradiction with readOnlyHint=true.

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?

Somewhat lengthy (multiple paragraphs) but front-loaded with core purpose, then details. Every sentence adds value, covering workflow, topics, detail levels, response fields, and constraints. Slightly verbose but 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 no output schema, the description fully documents the response structure (topic, focus, summary, etc.) and explains all 8 parameters with usage examples. It also covers detail levels, topics, and workflow, making it self-contained 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?

Description enriches all 8 parameters beyond the schema. For example, it expands on the topic values (identity='project name/type + which topics apply'), clarifies inline_files usage with a concrete example and required files, and explains detail_level outputs (brief ≤500 tokens; standard adds version health; full adds file tree).

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 defines a specific action ('scans manifests and config') and resource ('project stack & scripts'), listing 11 topics. It explicitly distinguishes from sibling tools (find_code, read_code, check_test, explain_architecture) by stating what it does NOT do.

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 (new session, user asks about stack/scripts/build) and when-not-to-call (symbol search, file bodies, wiring, tests). Also suggests a workflow ('topic=identity first on new repo → follow next_calls'), offering clear alternative tool references.

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 confirm read-only; description adds stateful behavior details (tracks hypotheses, loop detection, riskLevel blocking, credit limits) without 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?

Dense but well-structured: front-loaded with core purpose, followed by features, usage conditions, and example. No redundancy; 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?

Covers behavioral aspects, session handling, and limits but lacks explicit output description. Still sufficient for agent to understand tool behavior and response expectations.

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 covers 100% parameters with descriptions; description adds usage context like lastActions format and goalAnchor requirement, enhancing understanding 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?

Description clearly states it structures multi-step debugging and planning, differentiating it from sibling tools. Provides specific examples of usage, making purpose unmistakable.

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 when to call (e.g., stuck after 2+ failed attempts, auth/billing/schema changes) and when not to (e.g., fix known, single typo). Includes alternative 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 are blank (none true), but the description fully discloses behaviors: rejects sensitive text, max 200 memories, storage mechanism (stdio: SQLite, hosted: cloud), recall output format (up to 5 matches with content/type/area/age_days, ~500 token cap). No contradiction with annotations.

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

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

The description is long but well-organized with clear sections (actions, types, when to call, storage). Every sentence is informative, though slightly verbose for a tool with 12 parameters. Structure is logical and front-loaded with purpose.

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

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

Given 12 parameters, no output schema, and complex actions (remember/recall/list/forget), the description covers all critical aspects: action details, parameter semantics, usage guidelines, storage, limits, types, and post-call instructions. 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 coverage is 100%, but the description adds significant context: explains area is searchable, path must be consistent, scope meanings (project vs personal vs all), type detailed definitions, and after-call guidance for recall. Adds 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 'Persists short notes about this project across chat sessions' and distinguishes actions (remember, recall, list, forget). It explicitly contrasts with sibling tools like get_project_context and find_code, 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?

Provides explicit when-to-call (user says remember/recall/last time, before auth/billing/deploy, after non-obvious fix, new session) and when-not-to-call (stack/scripts use get_project_context, finding code use find_code, facts already in chat). This is comprehensive and practical.

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 declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds important behavioral details: 5 credits per success, free failures, token savings vs full-file Read, local-only call graph modes, and that every file in a batch returns. It explains truncation and pagination behavior, adding significant value 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 comprehensive but verbose, running multiple paragraphs. It is well-structured with clear sections (purpose, modes, costs, when-to-use), but some redundancy exists (e.g., repeated 'Read-only'). It trades conciseness for completeness, which is acceptable for a complex tool but not optimally 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 the tool's complexity (17 parameters, 8 modes, no output schema), the description covers every aspect: all modes with semantics, cost implications, parameter combinations, pagination, session dedup, and explicit alternatives for each scenario. It leaves no gap in understanding how to use the tool effectively.

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

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

Schema coverage is 100% with descriptive parameter descriptions. The tool description goes further by explaining mode-specific parameter usage (e.g., 'mode:file|outline' for files[], 'mode:symbol' for target/targets), and provides practical tips like pairing with find_code and setting detail_level. This guidance adds meaningful clarity 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 extracts code via tree-sitter AST and explicitly contrasts with repo-wide search. It lists eight specific modes (symbol, file, outline, etc.) and distinguishes from siblings like find_code and explain_architecture, making the purpose unambiguous.

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

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

The description provides explicit 'Call when' and 'Do NOT when' guidance, referencing sibling tools (find_code, get_project_context, explain_architecture). It also gives cheapest and expensive paths, leaving no doubt about proper use cases.

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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds key behavioral details: '2 credits hosted', 'No project path', 'Read-only', and explains the two-operation workflow (search then get) with prerequisites.

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 information-dense and front-loaded with the core purpose. However, it is somewhat lengthy and could be broken into bullet points or shorter sentences for easier scanning.

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

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

Given no output schema, the description adequately explains the tool's behavior, operations, and integration points. It covers prerequisites, examples, and error-avoidance guidance, making it fully actionable.

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?

Even though schema coverage is 100%, the description enriches parameter meaning by explaining how operation, query, slug, and category work together, including an example call. It clarifies that slug is required for 'get' and must come from a search hit.

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 provides expert developer playbooks, not a codebase, and distinguishes it from sibling tools like get_project_context, find_code, read_code, etc. It specifies the verb (search/get) and resource (knowledge base entries), 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?

Explicitly states when to use ('Call when standard patterns beat guessing'), gives concrete examples (wiring Stripe checkout, fixing auth middleware), and advises order ('Use AFTER repo tools'). Also lists what it is NOT for, referencing sibling tools.

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