Zephex

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

Annotations already declare readOnly/openWorld/idempotent, so the bar for added transparency is lower. The description adds substantial behavioral context beyond annotations: 'Blocks localhost/private IPs' is a critical safety disclosure; 'quick ~1–3s; scan_depth=deep for secret scan (~8–12s)' discloses timing; '6 credits hosted' discloses cost; 'Read plain_summary first; only drill into security_headers or secrets if grade is poor' gives a workflow behavior. All traits are consistent with the readOnly hint, so 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 every sentence earns its place: state purpose, list outputs, provide reading strategy, timings, credit cost, when-to-call, safety block, exclusions, an example, and read-only reminder. It is front-loaded with the most important information and uses semicolons to keep it tight. For a tool with 18 parameters, this is appropriately 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?

The description covers the essential context needed to safely and effectively invoke the tool: input constraints (public HTTPS URL), output summary (security grade, SSL, etc.), safety (blocks localhost/private IPs), cost (6 credits), performance expectations (quick vs. deep), usage flow (read plain_summary first), and a concrete example. Since there is no output schema, the description appropriately outlines the key return categories. The 18-parameter schema plus rich annotations make this 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 description coverage is 100% (18/18 parameters have descriptions), so the baseline is 3. The tool description mentions 'scan_depth=deep for secret scan' but the schema already explains deep scan behavior in the 'scan_depth' parameter description. No additional parameter semantics are provided beyond what is already in the schema, so the score stays at the 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?

The description opens with a specific verb and resource: 'Audit a public HTTPS URL the user deployed — security grade A–F, SSL, headers, cookies, health, exposed secrets, tech stack.' This clearly states what the tool does and enumerates its outputs. It also distinguishes from siblings with explicit exclusions: 'NOT for repo code (find_code), packages (check_package), tests (check_test), or project layout (get_project_context).' This is a model of purpose clarity.

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 precise when-to-use guidance: 'Call when user pastes a live URL — post-deploy check, is it secure, what framework, exposed keys.' It also provides an example call and explicitly names alternatives for non-matching cases, such as 'repo code (find_code), packages (check_package), tests (check_test), or project layout (get_project_context).' This is comprehensive usage direction.

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, and the description ends with 'Read-only' which aligns. Beyond annotations, it reveals return structure ('Returns summary, data, next_calls, meta.credits (5 hosted)'), task-specific behaviors (check/upgrade/security), and a key constraint ('No project path — just package name + version'). 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 dense but efficiently organized. It starts with a clear purpose, then lists task behaviors, return info, constraints, exclusions, and an example—all in a compact paragraph. Every sentence adds value, and the use of semicolons and em dashes keeps it readable despite the high information density.

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

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

Given the tool has 8 parameters, no output schema, and moderate complexity, the description is thorough: it explains return values (summary, data, next_calls, meta.credits), task-specific output differences, the 'no project path' constraint, and explicitly names sibling tools for exclusions. The internal parameters (channel, cli_depth) are already documented in the schema, so no gap exists.

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?

Although schema coverage is 100%, the description adds significant meaning beyond field names. It explains task values in detail (e.g., 'task=check: exists, slopsquat, deprecation, CVEs (pass version); task=upgrade|migrate: breaking_changes + migration_steps from release notes') and clarifies which versions are needed for which task. The example invocation ties parameters together.

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 opens with a specific verb and resource: 'Check a public registry package before install or version bump' and enumerates common packages (next, react, stripe). It explicitly differentiates from siblings by stating what it's NOT for (repo layout, import search, tests, architecture, live URLs) and names those sibling 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?

Clear when-to-use guidance is given: 'Call BEFORE npm install or bumping next/stripe/prisma.' It also provides explicit exclusions with alternative tool names: 'NOT for repo layout (get_project_context), import search (find_code), tests (check_test), architecture (explain_architecture), live URLs (audit_headers).' The example call further illustrates 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 already declare readOnlyHint=true and destructiveHint=false, and the description adds 'Does not modify source'. It further discloses billing (meta.credits, meta.charges_usage), session caching with no re-run, hosted vs. local stdio execution, and path restrictions — all beyond the structured fields.

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 and front-loaded, with the key purpose and outputs first. It contains an example and organized workflow, but it is quite long; some credit/billing detail could be condensed. Still, every sentence contributes value, so it earns a 4 rather than a 5.

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 17 parameters, no output schema, and a complex multi-task tool, the description is remarkably complete. It explains the task lifecycle, return fields, credit costs, path modes, scoping parameters, and exclusions — sufficient for an agent to select and invoke the tool correctly in most situations.

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 enriches parameter semantics significantly: e.g., 'Pass diff_base: main for failures_in_diff', 'area/file_filter scopes re-runs after a full run', 'task=missing scans git diff', 'session_id for session tasks', and inline_files as a hosted fallback. This guidance goes well beyond the raw 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?

States a specific verb and resource ('Run tests') with a clear list of structured outputs (fix_first, broken_areas, failure_clusters, coverage_by_area, blind_spots, deploy probes). Explicitly distinguishes from siblings by saying 'Not for finding which files to edit (find_code)' and lists other 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?

Provides a concrete workflow (detect → run → failures|missing|why|status|fix_prompt), explicit call triggers ('after every substantive edit', 'when user asks if tests pass or if tests are missing', 'before push'), and clear alternatives/don'ts (find_code, check_package, get_project_context, audit_headers). Also explains credit costs for when to use which task.

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 mark this as read-only and idempotent, and the description adds 'Read-only.' It discloses critical behavioral details: 'Hosted: 7 credits per success; failures free,' caching behavior ('Repeat identical calls hit server cache (meta.cache_hit) until force:true'), and performance degradation ('>10k files auto-degrades to overview'). It also documents the output envelope and data fields since there is no output schema.

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 and information-packed, with the core purpose in the first sentence. Every section adds value—cost, caching, output structure, usage boundaries—but the length is substantial. A more condensed layout could improve scannability, though the complexity of the tool justifies the detail.

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

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

Given no output schema and a complex tool (12 params, 3 modes, 8 focus values), the description thoroughly covers return data fields, envelope structure, cost behavior, caching, degradation, and explicit usage exclusions. It also notes confidence warnings and auto-degrade behavior, leaving minimal gaps 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?

Though schema coverage is 100%, the description adds meaningful context: concern is 'not a fixed keyword list' and uses 'find_code concept search + import graph'; seed_files are '1–20 paths from find_code'; mode cost implications are explained ('deep or audit on whole monorepo — use subpath'); focus values are expanded (auth=validation chain, etc.). This goes well beyond 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 specific function: 'Maps how files connect across a subsystem — roles and import edges, not file bodies.' This distinguishes it from siblings like read_code (bodies) and find_code (search). It also provides concrete use cases like 'Call BEFORE cross-cutting edits — how a feature spans modules, where to patch.'

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 and when not to: 'Do NOT for stack (get_project_context), search (find_code), bodies (read_code), tests, packages, live URL.' Names alternatives directly and suggests follow-up: 'After: next_calls → read_code outline on hub files.'

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

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

Goes well beyond annotations by disclosing the response envelope ('Envelope: intent, focus, summary, data.matches, files_hit, next_calls, meta.credits (5 hosted)'), token-capped behavior, AST ranking, and read-only nature. It also explains intent-specific behavior with examples like 'snippet=pasted line; symbol=known name; concept=topic+also_try synonyms; everywhere=rename map'. 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 dense but every sentence carries meaning. It is front-loaded with the primary directive ('PREFER over native Grep when location is unknown'), then organizes usage, exclusions, and output structure in a compact, scannable format. Despite its length, there is no filler or redundancy.

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

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

Given the tool's complexity (10 parameters, 4 intents, hosted vs stdio modes, no output schema), the description is remarkably complete. It covers response envelope, after-call workflow ('read summary + next_calls → read_code on top hit'), path/inline_files handling, and dependency on credits. It fully equips an agent to invoke and interpret 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?

Schema coverage is 100% with each parameter described, so baseline is 3. The description adds value by explaining how to choose intent values ('snippet=pasted line; symbol=known name'), when to use include ('include docs|config|data when markdown, JSON, or SQL matter'), and path semantics for stdio vs hosted. This clarifies parameter choices beyond the schema, justifying a 4.

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

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

The description clearly states the tool's purpose: 'Ripgrep + AST ranking across web, mobile, CLI, and monorepos' – a code search tool with scope and mechanism. It explicitly differentiates from native Grep and sibling tools via 'PREFER over native Grep' and the 'DO NOT' list naming alternatives like read_code and get_project_context.

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 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)') with named alternative tools. This is exemplary usage 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context: 'Secret-sanitized', '7 credits hosted', a guaranteed response contract ('Every response: topic, focus, summary, data.key_paths, hint, related_topics, next_calls, meta.credits'), cache-refresh behavior via force:true, and a final 'Read-only' confirmation. It enriches the safety profile without contradicting the 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 every sentence earns its place. It is front-loaded with the core purpose, then workflow, topic enumeration, output contract, usage conditions, and exclusions — structured with semicolons and lists that make it scannable. There is no fluff or repetition of schema field definitions; it only adds details not already in the structured data.

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?

This is a complex tool: 8 parameters, nested inline_files object, 11 topics, no output schema, and multiple sibling tools that could be confused. Despite that, the description covers the response format (since there is no output schema), the topic set, input modes, cost/credits, caching, and exclusions — effectively compensating for every complexity. It is as complete as one could hope for without the actual 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%, but the description adds meaningful nuance beyond the schema: it explains detail_level behavior ('brief ≤500 tokens; standard adds version health; full adds file tree'), clarifies inline_files usage ('Pass path ... or inline_files (package.json + 2-4 source files)'), and documents force:true semantics. It also provides guidance on choosing path vs inline_files. This is exactly the kind of added value the dimension calls for.

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 opens with a specific verb and resource: 'Scans manifests and config — one topic slice per call.' It enumerates what it detects (stack, scripts, monorepo, API routes, auth/DB providers, integrations, env vars) and explicitly distinguishes itself from siblings with a 'Do NOT' list (symbol search via find_code, file bodies via read_code, wiring via explain_architecture, tests via check_test). This is a clear, specific purpose that is easy to differentiate.

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 explicit 'Call when' conditions (new session; user asks stack, scripts, or how to run/test/build) and explicit exclusions with named alternative tools. It also provides a recommended workflow: 'topic=identity first on new repo → follow next_calls'. This goes well beyond basic usage and is exactly what an agent needs to select the right 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 goes far beyond annotations by disclosing side effects and constraints: loop detection via lastActions, blocking dangerous edits under high risk, projectBrief loading, suggestedRemember triggering project_memory remember, credit costs, and a session cap of 10 thoughts. These are non-obvious behaviors that the agent needs to know.

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 and lengthy, but every sentence adds unique value. It is structured logically from purpose to behavior to usage to parameter guidance to an example. Though somewhat long, the complexity of the tool justifies the length, and the example aids comprehension.

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 15 parameters, no output schema, and rich annotations, the description covers purpose, behavior, usage conditions, and parameter semantics substantially. It references response fields like thoughtConfirmed and shouldContinue, but doesn't spell out the full response structure, which is a minor gap given the tool's complexity.

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

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

While schema coverage is 100%, the description enriches parameter meaning with a concrete example and contextual notes like 'Pass lastActions (2–5 recent tool calls), goalAnchor after thought 2, sessionId to resume, area for subsystem.' This adds practical usage nuance beyond the schema's individual field 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 opens with a specific verb and resource: 'Structure multi-step debugging and planning across tool calls.' It clearly distinguishes itself from a one-shot think and outlines concrete behaviors like tracking hypotheses and detecting loops, making the tool's unique purpose unmistakable relative to sibling 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?

Provides explicit when-to-use criteria ('stuck after 2+ failed debug attempts...') and when-not-to-use conditions ('NOT when fix is known, single typo...'). This is a textbook example of usage guidance, including alternatives and exclusions.

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

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

The description is rich (limits, max 200 memories, ~500 token cap, rejects API keys) but directly contradicts the annotations: it describes 'forget: delete by uuid' (a destructive action) while destructiveHint=false. Per rubric, any contradiction yields a score of 1. Flagging as 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?

The description is lengthy but well-organized with action prefixes and usage bullets. Every sentence carries specific, non-redundant information (limits, types, storage). It earns a 4; a 5 would require tighter prose without losing the rich 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 no output schema, the description covers purpose, actions, limits, types, scope, storage, and usage guidance well. Recall's return shape is partially described (content, type, area, age_days), but list and forget response details are sparse. Overall, it is nearly complete for a multi-action 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% and the description adds practical semantics beyond the schema: it clarifies path reuse ('Use the same path on remember, recall, and list'), scope distinctions (project vs personal vs all), and action-specific required fields. This goes beyond baseline (3) but is not exhaustive.

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 persists project notes across chat sessions and differentiates from siblings: 'Not a repo scanner (use get_project_context for stack)' and 'finding code (find_code)'. It enumerates the four actions (remember, recall, list, forget) with specifics, leaving no ambiguity.

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

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

Provides explicit call-when conditions (user says remember/recall/last time; before auth/billing/deploy; after non-obvious fixes; new session) and do-not-call conditions (stack/scripts → get_project_context; finding code → find_code; facts already in chat). This is clear, actionable guidance with named 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?

Despite annotations already declaring readOnly/idempotent, the description adds substantial behavioral context: credit costs per success, hosted vs local disk limitations, SQLite call-graph index build behavior, file batch truncation ('never dropped'), and token-saving options like compact. It explicitly states 'Read-only' and does not contradict any annotation.

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 every sentence earns its place: it front-loads the core purpose, then systematically covers modes, costs, usage boundaries, and post-call behavior. The conditional and imperative structure ('Call when', 'Do NOT when', 'Cheapest path') makes the information actionable without 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?

For a tool with 17 parameters, 8 modes, no output schema, and complex behavioral nuances (hosted vs local disk, pagination, batch limits, credit costs), the description covers all essential decision points. It even addresses return context via the envelope and next_calls, making it complete for agent selection and 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?

While the schema already describes all 17 parameters, the description adds cross-mode semantics and strategies: which params pair with which modes (e.g., 'file: batch 1–20 paths, paginate offset_line'), performance trade-offs (symbol without find_code may scan many files), and envelope-level advice ('session_id dedupes across turns'). This goes beyond raw schema definitions and materially improves parameter selection.

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 opens with a specific verb and resource: 'Extracts code surgically via tree-sitter AST — not repo-wide search.' It names eight modes and explicitly distinguishes itself from siblings like find_code, explain_architecture, and get_project_context. This is a clear, resource-specific purpose that eliminates ambiguity.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'Call when: symbol or files[] known... Do NOT when: location unknown (find_code); stack (get_project_context); wiring map (explain_architecture); repo-wide grep (find_code).' It also offers cost/benefit guidance (cheapest path vs expensive modes) and a free alternative (editor Read on files under ~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 indicate readOnlyHint, deceptiveHint, and idempotentHint. The description adds valuable context: credit cost ('2 credits hosted'), no project path, the need to use search before get (slug must come from search), and 'Read-only' reinforces safety. No contradiction detected; it supplements annotations with operational 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 dense yet every sentence adds value: scope, operations, use cases, exclusions, and an example. It is front-loaded with the core concept ('Expert developer playbooks — not your repo') and structured logically. No filler or redundancy.

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

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

The description covers purpose, workflow, limitations, cost, timing, and explicit exclusions. Despite no output schema, it clarifies that get returns 'full guidance by slug' and search returns entries. It is sufficiently complete for an agent to select and invoke correctly in varied 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% with each parameter described. The description adds workflow semantics by explaining operation sequence (search first, get with returned slug) and provides a concrete usage example (Zephex_dev_info({ operation: 'search', query: 'Stripe webhook...', category: 'payments' })). This goes beyond the schema's static descriptions, earning a 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 identifies the tool as 'Expert developer playbooks' with specific operations (search by query, get by slug) and scope ('not your repo'). It explicitly contrasts with repo tools and lists concrete use cases like 'wiring stripe checkout' and 'Supabase RLS policies', making its 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-use guidance ('Call when standard patterns beat guessing'), when-to-use-after ('Use AFTER repo tools if code context is still thin'), and a detailed NOT list naming sibling tools (get_project_context, find_code, read_code, check_package, check_test, audit_headers, project_memory). This is exemplary usage guidance.

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