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, and destructiveHint=false. The description's final 'read-only' line is redundant with annotations, but it adds genuinely useful behavioral context beyond them: auto-detection of ecosystem, one-task-per-call semantics, version-specific result specificity, output reading order (summary and hint first, then inspected fields), and next_calls follow-up behavior. It does not contradict 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?

Long and dense, but it stays front-loaded and every sentence earns its place: the core purpose, trigger list, ordering constraint, task semantics, parameter rules, output-handling protocol, examples, and exclusions are all instruction-bearing. The trigger list is somewhat long and some phrases overlap with the install-ordering sentence, but the structure is clear.

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

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

For an 8-parameter tool with no output schema, the description leaves little unaccounted for. It states the exact task enum semantics, the version/from_version pairing rules, the auto-detection behavior, how to read the result (summary and hint first, then relevant data fields), and the next_calls follow-up flow. The only moderate gaps (e.g., exact return format) are mitigated by the described output-reading protocol.

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 the baseline is 3, but the description adds real semantic value: it warns to pass the public registry package name, not an import path or repository path; specifies which task requires which version (package version with check/security, from_version with upgrade/migrate/debug); gives concrete argument examples for express and next; and adds 'set ecosystem for ambiguous non-npm names' with 'set the ecosystem for non-npm names ambiguous.' This goes meaningfully beyond the bare schema.

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

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

States a specific verb+resource: verify a public registry package before installation, recommendation, or dependency changes. Names multiple concrete scenarios (safety, CVEs, typo/slopsquat, deprecation, breaking changes) and explicitly differentiates from siblings (not for find_code, not for get_installed_dependencies), so an agent can distinguish it without opening the schema.

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?

Gives an explicit ALWAYS trigger list (install, add package, upgrade, bump, migrate, is this package safe, check CVEs, etc.), a strict ordering rule (call before npm/pnpm/yarn/bun/pip/cargo/gem install; do not install first and inspect later), and a preference statement over web search and raw registry metadata. Also names when NOT to use it (installed dependencies, locale nding code). This is comprehensive and non-ambiguous.

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 establish readOnlyHint:true and destructiveHint:false, and the description corroborates and adds beyond structured data by disclosing session caching: it can be executed without re-running, and 'session_id persists across calls for the same run' but beware sub-concept of last-run. The description also carries the notable disclaimer that it 'does not invent a runner if none is present', 'does not modify test files...', and that a run is not re-executed on a status/read call but reuses the session. These are important behavioral traits: each call may be cached, and in hosted mode cannot accept a filesystem path.

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, front-loaded with the core purpose in the first sentence, followed by exclusions, use triggers, a workflow section, negative behavioral notes, and a brief example pair. Length is justified by the breadth (13 task values, 17 parameters), but a few repeated phrases (e.g., identical runner list, 'parsing no vs. not') could be tightened, so it is efficient but not maximally 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 tool is highly complex with 17 parameters and 12 task modes, and there is no output schema; the description compensates fully by listing the 10 named return fields (breakdown, coverage, fix_first, broken-area-failures...). It covers operation in both standard I/O and hosted contexts, gaits through a typical 'run then inspect failures' sequence, and states limitations ('no npm check', 'no scanning') and the count of an execution. Everything an interview agent needs to know to call it correctly for a given situation is present.

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 the baseline is 3: the input schema already documents `task`, `session_id`, `path`, `diff_base`, `question`, etc. Leading the description above baseline is workflow guidance: it orders which value to use whenlife — 'task=detect... then task=run; then failures|status|list|coverage|why|fix_prompt with session_id' — and semantics that cross parameters, like 'diff_base: main after edits' and 'area/file_filter scopes the next run.' It makes the orchestrations between task and other parameters meaning richer than the schema's enum 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?

Opens with a specific verb+resource: 'Run the project's real test suite and return structured health' — a precise, action-oriented statement of what it does. It further distinguishes itself from siblings by explicit negatives: 'not a file-picker for what to edit', 'Does not check npm packages', 'Does not scan a live URL', and names the terminal alias 'the same engine as zephex check test.'

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?

Gives extremely explicit triggers: 'ALWAYS use after you edited source, when they ask if tests pass, what is failing, why defects, green check, before commit, before push, or to re-run only failed tests.' It even names the alternative it replaces: 'PREFER this over running bun test, npm test, or pytest yourself and dumping logs.' Conditions like 'PREFER this over' and 'Use when not' make through when-to-use unambiguous; it also tells when NOT to: 'not a file picker for what to edit.'

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 convey read-only and non-destructive behavior, and the description adds meaningful behavioral context: it returns an architecture map, has empty-cluster semantics for absent labels, clarifies that outbound provider keys are not inbound login, and warns against opening many files manually. There is no contradiction with 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 front-loaded with the core purpose and the first sentence carries the essential meaning. It is long and dense, and its one-paragraph layout makes scanning harder, so it loses a point on structure despite every sentence carrying useful 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?

With no output schema, the description compensates by naming expected result fields (summary, data.entry_points, data.auth_flow, data.concern_cluster, next_calls), giving the follow-up workflow (read_code on hubs), covering the local/stdio/remote cases, and explaining what an empty cluster means. For a 12-parameter compositional analysis tool, this is a fully serviceable definition.

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?

Because the schema documentation covers 100% of parameters, the floor is 3, but the description adds clarifying semantics beyond the schema: 'concern' is any user label, not a fixed list, 'focus' maps to the slice the user named, 'path' behaves differently for local vs hosted, and it gives concrete invocation examples. Not every parameter gets extra treatment, so 4 is appropriate.

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

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

The description states a specific verb and resource: 'Map how files in the user's project connect' and clarifies scope with 'Not file bodies'. It also distinguishes itself from siblings like read_code and find_code, so an agent gets a crisp picture of what this tool is 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?

It gives explicit when-to-call triggers ('ALWAYS call when they ask how auth works', 'where to patch this feature'), a MUST-call condition for Zephex/MCP wiring questions, and an explicit not-for list naming sibling tools. It even advises preferring this over native Read on 10–20 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?

Annotations already declare readOnly, idempotent, non-destructive. The description adds significant behavioral context: results are ranked, definitions first, hand-off to read_code, rate limiting/throttle for concept intent, and output details (summary, matches, files_hit, next_calls). 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 with a clear intro, usage rules, parameter explanations, and examples. It is front-loaded with purpose. While verbose for a simple tool, the complexity of 10 parameters justifies the length. Could be slightly trimmed but still effective.

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

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

Given 10 parameters, no output schema, and complex behavior (intents, rate limits, hosted vs local, rename workflow), the description fully covers what the agent needs: when to use, how to construct queries, what to expect in results, and what to do next (call read_code). It even addresses edge cases like inline_files and next_calls.

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 goes beyond by providing examples for each intent, explaining whole_word usage with rename, and detailing also_try synonyms. This adds meaning but some parameter details are also in 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 'Search the user's project when you do not know which file holds something.' It uses strong action verbs and differentiates from siblings like read_code (exact location) and get_project_context (stack/scripts).

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 when to use ('ALWAYS call instead of guessing a path', 'ALWAYS call when the user says where is, find, who uses, usages, or rename'), when not to use ('Not for stack/scripts (get_project_context)', 'Not when you already have the exact file and symbol (read_code)'), and provides a clear alternative (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 indicate read-only, idempotent, non-destructive behavior. The description adds significant context: data comes from disk (not training), one topic per call, caching with force flag, transport-specific instructions (omit path for local, use inline_files for hosted), and that commands should be copied from data without guessing. 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 lengthy but every sentence earns its place given the tool's complexity (8 params, multiple topics, different transports). It is front-loaded with core purpose and critical 'ALWAYS call' rules. Slight verbosity from examples and repetition, but justified by preventing misuse.

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 8 parameters, no output schema, and annotations present, the description covers all bases: purpose, usage triggers, parameter semantics, return fields (topic, summary, data, hint, next_calls), caching behavior, transport handling, and disambiguation from siblings. It is fully complete for an AI agent to select 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% with descriptions for all 8 parameters. The description adds substantial meaning beyond schema: explains topic values in detail (identity, run, framework, etc.), provides usage examples (get_project_context({ topic: 'identity' })), clarifies inline_files format with explicit example, and ties parameters together in a workflow (start with topic=identity then follow next_calls).

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 answers project identity, stack, and run/test/build commands from disk, not training data. It explicitly distinguishes from siblings like find_code (function name) and read_code (file body), providing clear differentiation.

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

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

The description gives strong usage guidance: 'ALWAYS call this before you invent npm/pip/cargo commands or read package.json yourself.' It lists trigger phrases, specifies topics order (start with identity), and warns when NOT to use (for finding functions or reading files). Explicit alternatives are named.

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?

Annotations are sparse and non-destructive, but the description carries the behavioral burden well: it discloses persistent state, per-folder isolation, storage location differences (stdio vs hosted), that empty matches return nothing, and that the tool will not invent notes. It also explains that writes need sufficient detail ('not a one-liner'). It doesn't fully describe output shape, but with no output schema it provides more than enough behavior context.

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

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

The description is long but every sentence earns its place: trigger phrases, action rules, storage semantics, and an example are all required to make the four action modes safe to invoke. The trigger list could have been tighter, but it's front-loaded with the core mission first (persist across session), then action-specific details.

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 12 parameters and no output schema, the description covers: all four actions, required parameters per action, storage location differences, folder isolation, note limits (200 notes; ~2000 words), tag/area semantics, scope=all behavior, and empty match behavior. The biggest gap is a more explicit note on how recall returns matches[] and that the agent must read the content text to use it, but even that is addressed in the text ('read that text and use it').

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

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

The schema already covers 100% of parameters with descriptions, which sets a baseline. The description adds value beyond schema by describing required parameters per action ('id Required for forget', 'title/content Required for remember', 'query Required for recall'), gives a complete worked example, and explains how tags/area/title combine for search semantics. It might have explained more about the 'title' vs 'query' interplay, but it still exceeds what the structured schema provides.

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

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

The description opens with a specific verb+resource: 'Save project notes that must survive this chat.' It explains what the tool is for, explicitly states what it does NOT do ('Does not read source files'), and outlines the four actions (remember, recall, list, forget) that map to concrete behaviors. It clearly distinguishes itself from sibling file-reading/repo tools by focusing on persisted conversational memory.

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 trigger phrases ('remember, save this, don't forget...'), states when to prefer this tool over default chat memory, and specifies which action to use in each scenario ('If they ask what we saved, call list or recall'). It also provides guidance on scope, folder isolation, and when to include limit. This is among the most actionable usage guidance possible.

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 idempotentHint=true, indicating a safe read operation. The description adds substantial behavioral context: it explains the AST extraction approach cost vs whole-file reads, that it returns summary with data.symbols/data.files and next_calls for pagination, and how modes affect behavior (e.g., file mode returns all paths, symbol mode uses fuzzy search). It also notes constraints like local disk requirements for call graph modes and path fallback for hosted transport. 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 long but every sentence earns its place given the tool's complexity (17 parameters, 8 modes). It is front-loaded with the essential purpose and immediate usage rule, then systematically covers each mode. While it could be slightly tighter, the density of actionable information justifies the length. Structure with mode labels and bullet-tips is effective.

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

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

Given the tool has many modes, 17 parameters, and no output schema, the description provides a thorough overview. It explains what is returned (summary, data.symbols/files, next_calls), truncation behavior, and successfully bridges the gap between parameters and real usage. It covers edge cases like missing disk (inline_files) and pagination (offset_line, session_id). Minor gaps: the exact shape of symbol/file objects in the output is not detailed, but the description does reference prior hits and stubs to indicate reuse.

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 each parameter already has a description. However, the tool description adds strategic value beyond the schema: it explains the interplay between modes and parameters (e.g., 'detail_level=signature is enough to decide; body when you will edit', 'compact:true drops line numbers', 'batch files[] instead of opening one path at a time'). It also provides usage patterns like 'After find_code, do not re-search — pass the symbol as target or the path in files[].' This high-level guidance is not inferable from the schema alone.

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 reads a known symbol or file from the user's project without dumping the whole tree, using AST extraction. It distinguishes from siblings by explicitly telling when to prefer this over native Read (files over ~50 lines) and when to use find_code first or get_project_context instead. The verb 'Read' and resource 'symbol or file' are specific, and the many modes are well-scoped.

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 guidance: 'ALWAYS call when find_code just returned a name or path, when the user named a function to inspect, or before you edit a large file.' It also says when not to use: 'Not for unknown location (find_code first). Not for stack/scripts (get_project_context).' It names alternatives (find_code, get_project_context) and gives concrete examples for different modes. This is exceptional 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 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.