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

With no annotations, the description fully bears the burden of disclosing behavior. It details the tool's retry semantics, WAL journal mode, busy_timeout, and how it handles different database states. It also explains the output fields and their meanings.

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 longer than average but well-structured with sections for output fields and status semantics. It front-loads the purpose in the first sentence. While concise, the length is justified by the need for detailed behavioral guidance.

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

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

Given no parameters and an output schema exists, the description covers all necessary context: purpose, usage, behavioral details, output semantics, and decision rules for substrate code. It is fully complete for a health-check tool.

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

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

The tool has zero parameters, so the description cannot add parameter semantics beyond the schema. Baseline for 0 params is 4, and the description provides extensive context about the tool's operation and output, which compensates for the lack of parameters.

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

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

The description explicitly states 'Probe the scry project database and report health', with a clear verb and resource. It is distinct from siblings like scry_grep or scry_mint, which serve different purposes.

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

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

The description provides explicit guidance on when to use this tool, including distinguishing corruption from transient WAL lock contention, and interpreting status values ('ok', 'locked', 'corrupt') for substrate decisions. It also explains what to do when doc_count is null (fresh DB).

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

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

Describes return behavior (one hit per file, BM25-ranked), return JSON structure, and filter behavior. Lacks explicit statement about read-only nature, but overall transparent.

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

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

Well-structured with intro, args, return format, and tips. Front-loaded purpose, every sentence adds value, no fluff.

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

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

Covers purpose, usage, parameters (all 5 detailed), return JSON, and tips. No gaps given complexity and presence of output schema described.

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?

Each parameter is thoroughly explained with syntax examples (query FTS5, kind filter, path_glob pattern, etc.), adding significant value 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?

Clearly states 'Full-text search over all indexed file bodies' with verb+resource. Distinguishes from sibling scry_sql by noting broader full-text search vs curated marker fields.

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

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

Explicitly says 'use this when you want broad full-text search across file content, not just curated marker fields.' Provides tips for combining with scry_sql and prerequisite scry_surface call.

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

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

With no annotations, the description must disclose behavior. It explains collision detection and that the tool returns an ID and schema. However, it is unclear whether the tool modifies state (e.g., stores the marker) or if it is read-only. No mention of side effects, permissions, or destructive 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?

The description is detailed but lengthy, including extensive field quality guidance (summary, tags, rationale, etc.) that could be separated. It is structured with sections (Args, Returns, etc.), which helps, but efficiency is moderate.

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 only 2 parameters and an output schema described in text, the description covers purpose, parameter semantics, return format, and usage constraints. Missing error handling and sibling differentiation, but otherwise complete for a minting tool.

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

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

Schema coverage is 0%, so the description fully explains both parameters. 'kind' lists exact allowed values ('entry', 'anchor', 'bind') with examples. 'prefix' gives formatting rules per kind (dot required for entry, forbidden for anchor/bind). This adds critical meaning beyond the schema's bare type declaration.

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 generates a collision-free ID and returns marker schema, and is required before writing any @scry.* marker. It distinguishes its role from siblings like scry_mint_with_check, though not explicitly contrasting them.

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 starts with 'REQUIRED before writing any @scry.* marker,' giving explicit when-to-use guidance. It also provides conditional behavior for tier1 collisions (abandon ID if same logical concept). However, it does not compare against scry_mint_with_check or state when not to use this 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?

No annotations, but description fully discloses collision detection tiers (exact-prefix and family-slug neighbors), the abandonment logic, and the consequence of stranded IDs polluting scry. This is comprehensive behavioral transparency.

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

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

Description is well-structured with sections and bullet points, but contains some redundancy (e.g., 'stranded IDs pollute scry' could be integrated). Still efficient and easy to scan.

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 output schema exists, description explains return structure (id, marker schema, tier-1/tier-2 collision info). Input parameters fully described. Sister tool context is provided. No gaps.

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

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

Schema has 2 params with 0% coverage (no param descriptions in schema). Description adds significant meaning: explains kind values ('entry', 'anchor', 'bind') and prefix constraints (entry must contain dot, others must not). This compensates fully for schema lack.

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 the tool generates a collision-free scry marker ID and augments with warnings. It explicitly distinguishes from sibling scry_mint by stating 'PREFERRED over raw scry_mint' and describing additional collision detection.

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 'PREFERRED over raw scry_mint', telling when to use this tool vs sibling. Also provides guidance on when to abandon the new ID (if tier-1 hit is same logical concept) to avoid stranded IDs.

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

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

Without annotations, the description carries full burden. It explicitly states that scripts have 'read-write DB access' and 'return structured JSON', which are critical behavioral traits. No contradictions or omissions beyond what is reasonable for a script runner.

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

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

The description is extremely concise—three short paragraphs. It front-loads the purpose, then lists actions with bullet-style clarity. Every sentence is informative and necessary.

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 tool's purpose, actions, parameters, DB access rights, and return format. With an output schema present, it does not need to detail return values further. No gaps remain for typical agent invocation.

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

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

Schema coverage is 0%, so description must add meaning. It specifies that action can be 'list' or 'run', script is required when action='run', and params are optional arbitrary inputs. This fully explains the parameters beyond the schema's bare types.

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

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

The description clearly states the verb ('Run validation or transformation scripts') and resource ('with DB access'). It distinguishes between two actions (list and run), which differentiates it from sibling tools that handle other responsibilities like raw SQL or data checks.

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

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

The description provides clear guidance on when to use 'list' vs 'run' and notes constraints (script required for run). However, it does not explicitly exclude use cases or reference sibling tools as alternatives, which would improve clarity.

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

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

No annotations provided, so description carries full burden. Discloses that tool does not stage/commit, leaves unstaged changes, and fails under specific conditions. This is comprehensive behavioral information.

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

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

Description is front-loaded with main purpose and each sentence adds value. Slightly verbose but still efficient. Could be tightened without losing 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?

Covers all essential aspects: default vs. alternative behavior, failure conditions, what the tool does and doesn't do. With output schema present, no need to describe return values. Complete for a tool with one parameter.

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?

Only parameter is include_agent. The description explains its effect ('restore prior behavior: scrub everything and remove the agent/ directory entirely'), adding meaning beyond the input schema (boolean, default false). With 0% schema description coverage, this fully compensates.

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 verb+resource: 'Create a clean PR branch with all @scry.* markers stripped.' Distinct from siblings like scry_mint (create something else), scry_grep (search), 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?

Explicitly describes default behavior (excludes agent/** and AGENT.md), when to use include_agent=true, and failure conditions (main/master branch or dirty working tree). Provides clear context for use.

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

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

With no annotations provided, the description carries full burden and excels: it details atomicity, schema preservation, FTS trigger behavior, that disk markers are untouched, and the mandatory user confirmation. These go well beyond basic read/write tagging.

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: an evocative first line, clear technical details, a notable requirement (confirmation), parameter explanation, and return value. Every sentence serves a purpose with no redundancy.

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

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

Given the tool's complexity, the description covers purpose, tables affected, transactional behavior, side effects, parameter, and return format. An output schema exists to further detail the return structure, making this entirely sufficient.

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

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

Schema coverage is 0%, so the description must compensate. It does: the sole parameter `then_surface` is explained in detail, including its effect and equivalent operation ('reset + reindex'). This adds essential meaning beyond the schema's default value.

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

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

The description clearly states the tool's action: 'Lower the index back to disk-only state' and 'Truncates all scry index tables'. It uses specific verbs and resources, and distinguishes itself from the sibling `scry_surface` by offering the `then_surface` parameter to combine reset and rebuild.

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 implies when to use (to reset the index while preserving disk markers) and mentions the need for user confirmation. It does not explicitly compare to other siblings like `scry_scrub` or `scry_db_health`, but the context is clear enough for an agent to decide.

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

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

With no annotations, the description fully discloses read-only behavior, lists blocked keywords, and details the return format (JSON with results and row_count). It covers all behavioral traits an agent needs to know, including safety and output structure.

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 guidelines, followed by a well-organized table listing. Every sentence adds necessary context (constraints, table schemas, return format) without wasted words, achieving both conciseness and completeness.

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

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

Given the complexity of a SQL tool with many tables, the description is highly complete: it covers all tables, columns, constraints, supported queries, return format, and even references an alternative tool. The output schema exists, but the description adds sufficient detail for safe usage.

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

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

Although the input schema has 0% coverage and no parameter description, the description extensively compensates by listing available tables, columns, and query examples. This provides complete semantic context for the single 'query' parameter, adding immense meaning beyond the schema's simple type string.

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 executes read-only SQL queries against the scry database, specifying supported query types (SELECT and WITH) and explicitly blocking mutations. It distinguishes from siblings by mentioning scry_grep for file body searches, showing clear resource and scope.

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

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

The description explicitly lists use cases (discover state, search docs, check coverage, inspect anchors) and specifies supported query types while noting that mutators are blocked. It references an alternative tool (scry_grep) but does not explicitly state when not to use this tool beyond mutation prohibition.

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

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

Describes idempotency, content-hash dedup, behavior of force parameter (hard-delete vs missing_since), path scoping and reconciliation. No annotations provided, but description fully covers behavioral traits.

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

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

Well-structured with summary, usage, behavior, and parameter details. Slightly lengthy but justified by parameter complexity. 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?

Covers all aspects: purpose, usage, behavior, parameter details, return value. No missing context despite no annotations or output schema details.

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

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

Schema coverage is 0%, but description provides detailed explanations for both 'force' and 'path' parameters, including defaults, edge cases (e.g., path not existing returns error, scoped reconciliation). Adds significant meaning beyond 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?

Description clearly states 'Rebuild the DB from disk markers' and specifies use cases (after git pull, bulk moves, stale results). Contrasts with live file watcher, distinguishing from siblings like scry_mint and scry_scrub.

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 (after git pull, bulk moves, stale results) and when not to (file watcher handles live indexing). Provides clear advice for agent decision-making.

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