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

No annotations are provided, so the description must disclose behavior. It states it generates a document but does not clarify whether it writes to a file, returns content, or has side effects. It also fails to mention any permissions, limits, or output format, leaving key behavioral aspects ambiguous.

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

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

The description is a single, front-loaded sentence with a clear verb and object, followed by a parenthetical list of content categories. It is concise and contains no unnecessary words.

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 lack of annotations and output schema, the description should explain return values, side effects, and parameter behavior. It only covers purpose and content categories, leaving critical operational details absent for an export 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 schema has 0% description coverage for the only parameter, max_constraints. The description broadly references 'top constraints' but does not explain that max_constraints limits that section, nor its units or effect on other sections. The parameter semantics are only indirectly inferable.

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 uses a specific verb ('Generate') and identifies the resource ('CLAUDE.md document from the knowledge graph'), and it lists the included content categories (top constraints, recent decisions, known bug regions, co-edit patterns), distinguishing it from sibling tools that query individual aspects.

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 the tool is for producing an aggregated CLAUDE.md from knowledge graph data, but it does not explicitly state when to use this tool versus querying individual components via siblings like get_constraints or get_decision_log. It lacks explicit exclusions or 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?

With no annotations, the description carries the full burden of disclosing behavior. It doesn't state whether the tool is read-only, what the output looks like, or any side effects. The hint about 'similarity and status differences' is the only behavioral clue, but it's insufficient.

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

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

The description is a single sentence, which is concise and front-loaded, but it sacrifices necessary detail. It's not bloated, but it's under-specified. The brevity doesn't earn its place because it lacks critical 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?

The tool has two parameters, no output schema, and no annotations. The description provides no information about return values, parameter usage, or behavioral context. It is far from complete even for a simple 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 input schema has two parameters (limit, query) with zero descriptions, and the description doesn't mention them at all. Since schema coverage is 0%, the description fails to compensate, leaving the agent with no understanding of what these parameters do.

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

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

The description clearly states the tool finds pairs of contradicting facts, using a specific verb ('Find') and resource. It adds a hint of the method ('similarity and status differences'), but doesn't explicitly differentiate from sibling tools like resolve_contradiction, though the distinction is evident from the name.

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?

No guidance is provided about when to use this tool versus alternatives. It doesn't mention any exclusions or prerequisites, leaving the agent to infer usage solely from the vague description.

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 carries the full burden for behavioral disclosure. It explains the parsing action and its role in enforcement, but does not mention whether it performs a read-only operation, how missing files are handled, or any potential side effects. The context about automatic enforcement adds value but lacks depth.

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 two sentences, front-loaded with the main action and scoped to specific files. Every phrase contributes meaning, and the inspection/enforcement contrast adds valuable context without bloat.

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 and its relationship to PreToolUse enforcement, giving useful context. However, it omits parameter semantics and the exact return format (beyond 'declarative constraints'), which is especially important since there is no output schema. The lack of detail on expected inputs and outputs leaves gaps for an agent trying to invoke it 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?

The schema has two parameters (file_path and project_dir) with no descriptions and 0% coverage. The description does not mention either parameter, leaving their specific purpose and format ambiguous. For example, it is unclear if file_path is optional or relative to project_dir. The description fails to compensate for the complete lack of schema guidance.

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 parses AGENTS.md / CLAUDE.md / GEMINI.md / .agents/skills/*.md and returns declarative constraints. This specific verb+resource distinguishes it from the sibling tool get_constraints, which likely covers broader constraint sources.

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 notes that the data is 'Mixed into PreToolUse enforcement automatically' and that this tool 'exposes the same data for inspection,' implying it is intended for inspection/debugging rather than direct enforcement. It provides clear context but does not explicitly name alternatives or state when not to use it.

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 carries the full burden. It discloses the tamper-evident nature, the return content, and a runtime prerequisite (WORLD_MODEL_AUDIT_LOG=on). It adds meaningful operational context beyond a simple 'get' but stops short of stating read-only semantics explicitly.

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 only two sentences but packs in the purpose, return value details, use case, and a critical prerequisite. Every clause earns its place with 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?

For a no-parameter, read-only operation with no annotations or output schema, the description covers all essential aspects: what it does, what it returns, when to use it, and what server configuration is required. An agent has enough to deploy it 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?

There are zero parameters, so the schema is empty. The description explains what the tool returns, which is the only meaningful semantic content in this case. Baseline 4 applies since there are no parameters to describe.

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 uses a specific verb 'Return' and names the resource 'audit log head state' plus the 'closed-epoch chain', clearly defining what the tool does. This differentiates it from other audit-related siblings like get_compaction_audit.

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 explicitly states a use case: 'Compliance auditors call this periodically to verify no operator misbehavior has occurred since the last check.' This gives clear context on when to use it, but it does not mention alternatives or exclusions, so it misses the top score.

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 the full burden for behavioral disclosure. It mentions 'based on historical patterns' which adds some context, but it does not describe whether the operation is read-only, how suggestions are ranked, what format the results take, or any potential side effects. This is insufficient for full 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?

The description is a single, concise sentence that is front-loaded with the action and resource. Every word earns its place, and there is no superfluous content.

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 simple with two parameters, but the description leaves major gaps: no usage guidance, no parameter details, and no mention of return values (no output schema). For an agent to use this correctly, it needs more context about how suggestions are generated and what to expect from the response.

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 input schema has zero description coverage (0%) for its parameters, and the description does not compensate. It references 'the given file' (mapping to file_path) but does not clarify the expected format, the meaning or usage of 'limit', or any constraints. The description adds minimal value 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?

The description clearly states the verb 'Get' and the resource 'files commonly edited alongside the given file', with the basis 'historical patterns'. It is specific and distinguishes itself from the sibling tools, none of which share a similar focus on co-edit suggestions.

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 no guidance on when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or conditions, leaving the agent without context for selecting it among the many sibling tools.

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 the transparency burden. It discloses the ordering (most-recent first) and the available filters (session_id, limit), which is useful. However, it does not mention whether the operation is read-only, whether limit has a default, or describe the return format or pagination behavior.

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

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

The description is a single, front-loaded sentence that delivers all key information without redundancy. Every clause adds functional value, and there is no wasted text.

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 simple list/filter tool, the description covers the essential purpose and options. However, with no output schema and no annotations, the agent is left without knowledge of the returned fields, default limit behavior, or error cases. This is adequate for simple use but not fully complete.

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

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

Schema coverage is 0%, so the description must add meaning. It does clarify that session_id filters and limit controls the count, which is helpful. However, the semantics are shallow: it does not specify whether limit is mandatory, its maximum/default value, or whether session_id requires exact or partial matching.

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 lists compaction audit entries in reverse chronological order. It names the specific resource (compaction audit entries) and the action (list), which differentiates it from write-oriented siblings like record_compaction_audit. However, it does not explicitly distinguish from the similar get_audit_log_head tool, preventing a perfect score.

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 usage for inspecting compaction audit history, and the mention of filtering suggests relevant scenarios. However, it provides no explicit guidance on when to prefer this over alternatives like get_audit_log_head, and there are no exclusions or prerequisites stated.

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 are provided, so the description carries the burden. It implies a read-only operation ('Get') but does not disclose potential behaviors such as error handling for missing files, whether it searches the entire repository, or if any filtering is applied beyond the optional constraint_types parameter. The description adds some clarity by defining constraints, but does not reveal side effects or edge cases.

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

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

The description is a single, front-loaded sentence that efficiently communicates the tool's purpose without extraneous words. It earns a high score for being concise and structured.

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 simplicity (read operation, 2 parameters, no output schema), the description is mostly complete. It states what the tool does and the schema covers parameter details. However, it does not specify the return format or behavior when no constraints are found, which could leave some ambiguity for the agent. Still, for a straightforward getter, it is adequate.

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 description coverage is 0%, so the description must compensate. It does so by explaining that constraints include 'linting rules, patterns, conventions', which helps interpret the constraint_types enum. However, it does not explicitly map parameters or explain the file_path semantics beyond the name. The schema itself provides the enum values, offering adequate baseline coverage.

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 retrieves constraints for a file, using the verb 'Get' and specifying the resource and scope. It also clarifies what constraints are (linting rules, patterns, conventions). However, it does not explicitly distinguish from the sibling tool 'get_agents_md_constraints', which may overlap in purpose for specific files.

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 usage when constraints for a file are needed, but provides no explicit guidance on when to use this tool versus alternatives like 'get_agents_md_constraints' or when not to use it. It lacks exclusions and alternative recommendations.

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 the full burden of behavioral disclosure. It lists the content components but does not state whether the tool is read-only, how errors are handled, what the risk score means, or how the bundle is returned. This is a significant gap for a retrieval tool.

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

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

The description is a concise noun phrase that front-loads the core purpose and lists contents, but it lacks a verb and reads more like a label than a full sentence. It is not overly verbose, yet it could be more structured with a clearer main clause.

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 two parameters, no annotations, and no output schema, the description is too sparse. It does not explain the output format, the meaning of the risk score, or how this bundle relates to the individual context tools. The description leaves significant gaps in understanding.

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 input schema has 0% description coverage. The description mentions 'file' which maps to file_path, but action_type is only implied by 'editing' and not explicitly explained. The enum values (edit, create, delete, refactor) are not described, so the description adds minimal meaning beyond the schema.

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

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

The description clearly identifies the tool as a pre-action context bundle for a file, listing specific content types such as constraints, decisions, bugs, co-edits, related facts, and risk score. This distinguishes it from sibling tools that target single context types. However, the phrase 'before editing' is slightly inconsistent with the action_type enum which includes create, delete, and refactor.

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 does not provide explicit guidance on when to use this bundle versus the many sibling tools like get_constraints or get_related_bugs. It implies usage before an action, but there are no exclusions or alternative recommendations, leaving the agent to infer the appropriate context.

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 carries full burden. It implies a read operation via 'Get', but does not disclose behavior such as default limits, ordering, filtering effects, or whether it is purely read-only. The description focuses on content, not operational behavior.

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?

A single, front-loaded sentence with no wasted words. It efficiently states the purpose without 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 tool has four parameters, no output schema, and no annotations, yet the description provides no details on return value, parameter usage, or edge cases. It is overly minimal for the tool's apparent 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?

Schema coverage is 0%, and the description does not explain any parameters. It only hints at decision_type through 'corrections', but limit, file_path, and session_id are completely unaddressed.

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 retrieves 'decision traces' with specific content (agent proposals and human corrections), using a specific verb 'Get' that distinguishes it from sibling write tools like record_decision and record_correction.

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?

No guidance is provided on when to use this tool versus alternatives such as get_audit_log_head or get_compaction_audit. There is no mention of scenarios, exclusions, or preferred contexts.

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 carries the burden. The term 'diagnostics' implies a read-only operation, and the listed categories provide concrete insight into what the tool examines. However, it does not explicitly state whether any state is modified or note any performance implications.

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

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

The description is a single concise phrase that effectively communicates purpose and scope without wasted words. It is front-loaded and every element adds value.

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

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

For a zero-parameter diagnostic tool with no output schema, the description provides sufficient context about the report's contents. It could be improved by noting the output format, but the current level is adequate for understanding the tool's purpose.

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 need not document inputs. The baseline of 4 is appropriate because no parameter information is required.

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 function as memory health diagnostics and enumerates specific areas it covers (orphans, stale facts, contradictions, decay candidates, DB sizes). This distinguishes it from narrower sibling tools like find_contradictions or get_compaction_audit.

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 use for overall health assessment, but it does not explicitly state when to prefer this tool over siblings or when not to use it. No alternative tools are mentioned, so guidance is only implied.

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 are provided, so the description must carry the full burden. It only says 'Return...' without disclosing whether this is a read-only operation, any side effects, how 'compact' is achieved (e.g., truncation, filtering), or what happens if parameters like max_facts are omitted. This lack of behavioral detail is a significant gap.

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

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

The description is a single, front-loaded sentence with no filler. It is concise and easy to read, though it sacrifices substance for brevity.

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 4 parameters, zero schema coverage, no annotations, and no output schema, the description is insufficiently complete. It gives a high-level purpose but lacks details on parameter behavior, return format, and how this tool fits with alternatives. More context is needed for an agent to use it reliably.

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 0%, so the description must compensate, but it does not. It mentions two of the three event_type values but does not explain max_facts, max_constraints, project_hint, or the SessionStart event. The term 'compact' weakly implies size limits, but no explicit parameter meaning is provided.

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 returns a 'compact constraint+fact bundle' for specific hooks (PostCompact/UserPromptSubmit), which distinguishes it from sibling tools like query_fact or get_constraints. However, it could be more explicit about what 'context loss' entails or how it differs from get_context_for_action.

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 names specific trigger events (PostCompact/UserPromptSubmit) and the goal of re-injecting after context loss, giving clear context for when to use the tool. It does not explicitly mention alternatives or when not to use it, but the event-specific framing provides adequate 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?

With no annotations, the description alone should disclose whether this is a read-only operation, what data it accesses, and what 'assess regression risk' means behaviorally. It does none of this, leaving the agent to guess about side effects, return values, and underlying logic.

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

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

The description is a single, front-loaded sentence that uses every word efficiently. It is easy to read, though the terseness contributes to under-specification; still, it earns a high mark for conciseness.

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 there is no output schema and no annotations, the description should explain what the tool returns (e.g., a list of bugs, a risk score, or both) and provide context about the file path. It does not, making the tool's behavior and expected output opaque for a moderately complex action.

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 has 50% description coverage (only change_description is described). The tool description does not elaborate on the required 'file_path' or how 'change_description' affects the risk assessment, so the agent has no additional semantic understanding beyond the schema's minimal info.

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 action ('Get bugs fixed in a file') and the resource, and adds a secondary purpose ('assess regression risk'). It is specific and distinct from sibling tools focused on prediction, but the risk-assessment part is vague about what form it takes.

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?

No guidance is provided on when to use this tool versus alternatives like 'predict_regression' or 'simulate_change'. The description implies a use case (when you want to see historical bugs and regression risk for a file) but gives no exclusions or explicit when-not-to-use conditions.

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 carries full burden. It discloses that the tool converts PR comments into learned constraints, indicating a write operation to the knowledge graph. However, it does not mention idempotency, overwrite behavior, permissions, or any side effects beyond the conversion, which is minimal for a mutation tool.

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

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

The description is a single sentence that directly states the action and outcome with no filler. Every word contributes to the meaning, making it highly efficient and easy to parse.

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 has only two optional parameters and no output schema, so minimal description might suffice. However, because it is an ingest operation affecting the knowledge graph, a bit more context about result expectations or side effects would improve completeness. It is adequate but not fully comprehensive.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds no extra parameter-specific meaning beyond what the schema already provides (repo auto-detection, count default/max). It does not compensate for any missing details, but none are missing.

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 uses specific verbs ('Pull' and 'convert') and identifies the resource ('GitHub PR review comments') and target ('knowledge graph'). It clearly distinguishes itself from sibling tools like get_constraints or record_event by describing a unique ingest-and-transform workflow.

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 usage when you want to bring PR review comments into the knowledge graph, but it does not explicitly state when to prefer this over alternatives or provide exclusions. Sibling tools like record_correction or validate_change serve different purposes, yet no direct comparison is offered.

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 the full burden and exceeds expectations by disclosing persistence ('Persists into the annotations table'), audit integration ('chains into the same Merkle audit log as agent writes'), version/ADR references, and the rationale size limit. This gives the agent a clear behavioral model.

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 two sentences, front-loaded with the core action, and includes only essential extra context (persistence, audit log, limit). Every sentence earns its place with no filler.

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 6 required parameters, no output schema, and no annotations, the description provides solid context for a write operation: it explains persistence and audit chaining. It lacks explicit error handling or return behavior, but that is not critical for a basic mutation tool. The description is largely complete for 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?

The input schema has 83% coverage (5 of 6 parameters have descriptions), so the baseline is 3. The description adds little beyond the schema; it mentions the 8 KB rationale limit (already in schema) and does not elaborate on parameter meanings or relationships. The schema itself is well-documented, so a baseline score 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 clearly states the tool's action ('Attach') and object ('a signed human annotation to a span of agent events'). It distinguishes from siblings like record_event by emphasizing human annotation vs agent events and mentions specific annotation types.

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 the use case of attaching human notes or overrides to event spans, but provides no explicit guidance on when to choose this tool over alternatives such as record_correction or record_decision. The context is clear but lacks exclusions or alternative recommendations.

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 are provided, so the description carries the full burden. It discloses what the tool uses (past bugs, test failures, constraint violations) but does not state whether it has side effects, permissions requirements, or what the output looks like. The methodology hint adds some behavioral context, but safety and operational traits remain undisclosed.

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

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

The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the tool's purpose and key inputs.

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 two simple parameters and no output schema, the description is adequate for tool selection but does not fully prepare the agent for invocation. It lacks details on input semantics and return value format, though the simplicity and sibling context make it acceptable but not thorough.

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 0%, so the description must compensate. It mentions 'proposed change to a file' which loosely maps to file_path and change_description, but it does not clarify parameter formats, required fields, or examples. The description adds minimal meaning beyond what the property names already imply.

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 uses a specific verb ('Score') and resource ('regression risk') with the basis ('past bugs, test failures, and constraint violations'). It clearly distinguishes from siblings like predict_test_failures (which targets test failures specifically) and simulate_change (which simulates changes).

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 usage for assessing regression risk of a proposed change to a file, but it does not explicitly state when to prefer this tool over alternatives or provide exclusions. Sibling tools like predict_test_failures or validate_change could overlap, and no guidance is given on choosing among them.

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 must carry the full burden for behavioral transparency. It only states the core action without disclosing whether the operation is read-only, what data it relies on, what output format to expect, or any limitations. The description is minimal and leaves the agent without important contextual cues.

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

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

The description is a single, well-structured sentence that front-loads the action and avoids redundancy. Every word contributes to the core purpose, making it highly concise and easy to parse.

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 relatively simple (one parameter, no output schema, no annotations), but the description is thin. It communicates the essential purpose, but does not explain what the tool returns (e.g., a list of test names) or provide operational boundaries. It is minimally complete for selection but not fully adequate for invocation without further inference.

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 input schema has no descriptions for the parameter file_paths (0% coverage). The description adds semantic value by indicating these are 'edited files', clarifying the parameter's intent. However, it does not specify path format, file existence requirements, or other constraints that would be useful.

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 uses a specific verb 'Surface' with a clear resource ('tests likely to fail') and a scope condition ('given a set of edited files'). This distinguishes it from sibling tools like predict_regression and get_related_bugs, which address different aspects of change impact.

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 phrase 'given a set of edited files' implies the primary use case, but the description does not explicitly state when to use this tool over alternatives or provide any exclusions. It lacks guidance on how to compare with similar tools like predict_regression.

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 the full burden of behavioral disclosure. It reveals the action 'promote' but does not disclose side effects, permissions required, reversibility, or the fact that it likely mutates multiple projects. This leaves significant behavioral uncertainty.

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

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

The description is a single, concise sentence that front-loads the verb and object. It contains no filler or unnecessary detail, making it easy to parse and understand.

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 has no output schema and no annotations, and the description is minimal. It lacks essential context about the promotion's effects, error conditions, prerequisites, and return values. For a cross-project mutation tool, this is insufficient for an agent to use safely.

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 0%, so the description must compensate for parameter meaning. It implies constraint_id identifies the constraint, but it does not explain target_projects, its optionality, or how it interacts with the default 'all other registered projects'. The description adds minimal meaning beyond the schema.

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

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

The description uses the specific verb 'promote' with a clear resource, 'constraint', and a clear scope, 'from this project to all other registered projects'. This distinguishes it from sibling tools like get_constraints (retrieval) and validate_change (validation), making the purpose unambiguous.

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

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

No usage guidance is provided. The description does not mention when to use this tool versus alternatives, nor any prerequisites or conditions for promotion. It only states the action itself, leaving the agent without context for decision-making.

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 are provided, so the description carries full burden. It discloses the exact bundle components (entry, signed epoch, Merkle proof, epoch chain), required server flag, and all error cases, giving a thorough behavioral profile.

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

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

The description is a single information-dense sentence that front-loads the primary action ('Return a cryptographic inclusion-proof bundle') and then enumerates bundle contents and failure modes without unnecessary filler.

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 listing the bundle components explicitly. It also covers prerequisites and error scenarios, making it complete enough for a single-parameter 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% (row_id with description), but the description adds semantic value by specifying that row_id refers to fact, constraint, event, or decision ID, clarifying the expected input beyond the schema.

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

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

The description clearly states the tool returns a cryptographic inclusion-proof bundle for a persisted row_id. It names the specific resource (audit log entries) and distinguishes it from siblings like get_audit_log_head or query_fact by focusing on inclusion proofs.

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 explains when to use it (to prove inclusion of an entry), prerequisites (WORLD_MODEL_AUDIT_LOG=on), and error conditions (opt-in off, row_id not found, unclosed backlog). It does not explicitly mention alternatives, but the scope is clear enough to guide selection.

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 are provided, so the description carries full responsibility for behavioral disclosure. It doesn't state whether the tool is read-only, what the response format is, or that it can retrieve 'rules' and 'procedures' despite being named 'facts'. The term 'facts' may mislead users into thinking only fact-type content is returned, leaving important behavior undisclosed.

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

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

The description is a single, well-structured sentence that is front-loaded with the action and resource. Every word contributes to the core purpose without fluff or repetition. It 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?

For a general-purpose query tool with no output schema and no annotations, the description is minimal but adequate. It does not explain return values, pagination, or how to decide between this and related sibling tools. The ambiguous scope of 'facts' (vs rules/procedures) is a notable gap, but the schema partially covers this via content_type descriptions.

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?

Input schema coverage is 100% with descriptive text for all parameters, so the baseline is 3. The tool description adds no parameter-level meaning beyond what the schema already provides; it only reiterates the general entity focus. The description does not compensate or enhance the schema's parameter docs.

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 uses a clear verb ('Query') and resource ('knowledge graph') and specifies the object ('facts about entities'). It lists example entity types (APIs, functions, classes) which conveys scope. However, it doesn't distinguish itself from sibling tools like search_global that might also search the knowledge graph, so it lacks explicit 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?

There is no guidance in the description about when to use this tool versus alternatives. The only usage hint ('Use "procedure" to explicitly summon procedures...') appears in the schema's content_type parameter, not the tool description, and it is parameter-level rather than tool-level. No when-not-to-use or alternative tool references are provided.

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 are provided, so the description carries the full burden of behavioral disclosure. It only says 'Hydrate' without explaining whether the operation is read-only, what happens with invalid ranges, whether there are performance or memory implications, or what the response contains. This is a significant gap for a data-retrieval tool.

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 two sentences and front-loaded with the core action. Each sentence contributes meaning: the first states the operational scope, the second provides the motivating use case. It is well-structured and free of fluff, though slightly vague.

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 annotations, no output schema, and a 0% parameter coverage, the description should provide more contextual information about return values, error handling, and when to choose this tool. The current description is insufficient for an agent to confidently invoke the tool correctly in all cases, even though the tool itself is relatively simple.

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 0%, so the description must compensate. It mentions 'by line range,' which somewhat clarifies line_start and line_end, but it does not explain session_id, the inclusive/exclusive nature of the range, defaults, or behavior when only one line parameter is provided. The description adds minimal semantic value beyond the schema fields.

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 hydrates a Claude Code session transcript by line range, with a specific use case of tracing facts to their source conversation. This distinguishes it from sibling tools like query_fact, which focus on facts rather than raw transcript retrieval. However, the verb 'hydrate' is somewhat jargon-heavy, and it lacks an explicit contrast with related 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?

The description implies when to use the tool ('Lets agents trace a fact back to the exact conversation that produced it'), which provides some context. However, it does not explicitly state when to prefer this over alternatives like query_fact or get_audit_log_head, nor does it give exclusions or prerequisites. The guidance is present but inferred rather than explicit.

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 exist, so the description must disclose behavioral traits. It states it records an event, implying a write operation, but does not mention side effects, whether data is appended or overwritten, permissions, or failure modes. This is a significant gap for a tool with no annotation coverage.

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 exactly two sentences, front-loaded with the core action and followed by the purpose. Every word adds value with no redundancy or filler.

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 7 optional parameters, no output schema, and no annotations, the description does not fully equip an agent to use the tool. It lacks information about expected return values, whether any parameters are required in practice, and how this differs from other record_* tools beyond the compaction focus. This is insufficient for 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?

Schema coverage is 0%, so the description must compensate. It mentions 'token counts' and 'what was re-injected,' which roughly maps to pre_compact_tokens, post_compact_tokens, facts_injected, and constraints_injected, but it does not explain parameters like injection_event, session_id, or raw_summary. This leaves meaningful ambiguity.

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 uses the specific verb 'Record' with the resource 'context-compaction event' and specifies token counts and re-injected content. It clearly distinguishes from siblings like get_compaction_audit (retrieval) and record_event (generic event) by focusing on compaction-specific auditing.

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 context: this is for recording compaction events for audit purposes. It does not explicitly mention alternatives or when not to use it, but the specialized language makes the use case evident. There are no exclusions or alternative references, but the context is strong enough.

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 the full burden of behavioral disclosure. It only states the action is a 'high-priority learning signal', which hints at importance but does not describe side effects, persistence, reversibility, permissions, or any consequences of invoking the tool. This is a significant gap for a mutation-like recording tool.

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

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

The description is a single, grammatically complete sentence of about ten words. It is front-loaded with the core verb and resource, and the parenthetical adds context without redundancy. Every word earns its place; there is no fluff or tail-heavy content.

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 involves nested object parameters, no annotations, and no output schema, yet the description stays at a high level. It does not explain how to structure claude_action or user_correction, what counts as a valid correction, or what the tool returns. This leaves an agent under-informed for correct invocation, especially given the complexity of the 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 75%, and the description adds no additional meaning beyond what the schema already provides. The phrase 'user correction to Claude's output' loosely maps to claude_action and user_correction but does not clarify their structure or relationships. The 'reasoning' and 'session_id' parameters are not addressed at all in the description.

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 uses a specific verb ('Record') and identifies the resource ('a user correction to Claude's output'), which clearly conveys the tool's function. The parenthetical '(high-priority learning signal)' adds useful context. However, it does not explicitly differentiate from sibling tools like record_event or record_decision, though 'correction' provides some distinction.

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 the tool should be used when a user corrects Claude's output, but it gives no explicit 'when to use' vs. alternatives, no exclusions, and no prerequisites. Sibling tools with overlapping purposes (e.g., record_event, record_decision) are not referenced, leaving the agent without clear selection criteria.

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 carry the full burden of behavioral disclosure. It explains what is recorded but not whether the operation is append-only, idempotent, permission-sensitive, or what happens on conflict. No mutation or safety details are given.

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

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

The description is a single, well-structured sentence that is front-loaded with the core action and object. No filler or redundant wording.

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 7 parameters including nested objects and required fields, the description is far too minimal. It leaves the agent without guidance on required inputs, the decision_type enum, or the structure of nested objects, and there is no output schema to aid expectations.

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

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

Schema description coverage is 0%, and the description only hints at 'proposed' and 'human responded', which loosely map to agent_proposal and human_correction. It does not explain required parameters like session_id or decision_type, nor the enum values.

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's purpose: recording a decision trace with the agent's proposal and human's response. The verb 'record' and resource 'decision trace' are specific, though it doesn't explicitly distinguish from siblings like record_correction or record_event.

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?

No guidance is provided for when to use this tool versus the many sibling tools (e.g., record_correction, record_event). The description does not mention contexts, prerequisites, or 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?

With no annotations, the description carries the full burden of behavioral disclosure. It only says 'Record' implying a write operation, but doesn't explain persistence, idempotency, success/failure effects, or whether it appends to a log. This is insufficient for a mutation tool.

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 one short sentence, which is concise, but it under-specifies the tool's behavior. While brevity is good, the sentence doesn't earn its place by providing necessary context, making it closer to under-specification than effective conciseness.

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 7 parameters, no output schema, and no annotations, the description is far from complete. It doesn't explain required fields, return values, or how the event data is used. The description is only a high-level purpose statement, inadequate for safe and correct 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 only 29%, so the description must compensate for missing parameter details. It adds examples for event_type ('file edit, test run'), which is redundant with the enum, but it doesn't explain session_id, description, success, or reasoning. The description adds minimal semantic value beyond the schema.

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

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

The description states the general action ('Record a development event') with examples, so it's more than a tautology. However, it's vague about what constitutes a 'development event' and doesn't distinguish from sibling record tools like record_test_outcome or record_correction, which likely overlap in purpose.

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

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

No guidance is provided on when to use this tool versus alternative record tools. The description doesn't mention any conditions, prerequisites, or exclusions, leaving the agent without direction for tool selection.

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 carries the full burden. It implies a write operation but does not disclose side effects of linking failures, whether it is idempotent, or if it requires an existing session. This lack of behavioral detail leaves the agent uncertain about the tool's impact.

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

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

The description is a single sentence with no filler or unnecessary details. It efficiently conveys the main purpose and a secondary linking behavior, making it 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 tool has no annotations, no output schema, and a moderately complex input schema with a nested array. The description omits critical information about expected input formats, return behavior, and how the linking works. An agent would likely need additional schema inspection or external knowledge to use this tool confidently.

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 0%, and the description does not reference session_id or test_results at all. It fails to explain what session_id should be or how to structure the test_results array. The schema provides names/types, but the description adds no semantic value, making it insufficient.

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 core action ('Record test results') and adds a distinguishing feature ('link failures to recent code changes') that separates it from sibling tools like record_event or record_decision. It is not a mere tautology because it specifies the linking behavior, though it could be more explicit about the 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?

There is no guidance on when to use this tool vs alternatives. It does not mention prerequisites, exclusions, or contexts where other record tools would be more appropriate. The agent must infer usage from the name and minimal description.

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 are provided, so the description carries the full burden of disclosing behavioral traits. It only mentions the strategy selection and does not disclose side effects, persistence, reversibility, or what happens to the losing fact. This is a material gap for a tool that presumably modifies state.

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

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

The description is a single, front-loaded sentence that immediately states the primary action and enumerates strategies in a parenthetical list. Every element serves a purpose, with no fluff or redundant repetition of schema information.

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

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

Given the absence of annotations, output schema, and any behavioral details, the description is far from complete. It fails to explain return values, the outcome of the resolution (e.g., which fact is updated), or any prerequisites. This is a mutation-like operation with substantial missing context, making the tool risky to 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?

The schema provides no descriptions (0% coverage), so the description must compensate. It lists possible strategy values, which adds some meaning, but it does not explain the semantics of each strategy (e.g., what 'auto' does) or describe the 'fact_a_id', 'fact_b_id', and 'notes' parameters beyond their schema names. The compensation is partial and insufficient.

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 uses the specific verb 'Pick a winner' and identifies the resource as 'two contradicting facts,' clearly indicating the tool's purpose. It differentiates from sibling tools like find_contradictions by focusing on resolution rather than detection, though it doesn't explicitly name alternatives.

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 usage when a contradiction exists between two facts and provides a list of strategies, which serves as guidance on how to resolve. However, it lacks explicit exclusions or directives about when not to use this tool versus alternatives, leaving some ambiguity.

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 the full burden of disclosing behavioral traits. It does not mention whether the operation is read-only, how results are returned, or any side effects, leaving significant ambiguity.

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

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

The description is a single concise sentence with no redundant words. It is efficiently phrased, though it lacks additional structured information that a more complete description might include.

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 search tool with no output schema and no annotations, the description is minimally sufficient but incomplete. It omits return format, pagination behavior, and the meaning of 'entities', leaving the agent without critical execution context.

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 input schema includes 'query' and 'limit' with no descriptions, and the description adds no parameter-specific information. It does not explain what query syntax is expected or how limit affects results, failing to compensate for the 0% schema description coverage.

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 action (search), the resource (entities), and the scope (across all registered world-model projects). It distinguishes itself from potential siblings by emphasizing the global scope, though it does not explicitly name alternatives.

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?

There is no guidance on when to use this tool versus alternatives like query_fact. The description only states what it does, leaving it to the agent to infer appropriate usage without any exclusions or comparative context.

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 are provided, so the description carries the full burden. It states that the tool populates the knowledge graph but does not disclose whether the operation is idempotent, whether it modifies existing data, or any side effects. The 'force' parameter hints at re-seeding but this behavior is not explained in the description.

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

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

The description is a single sentence, direct, and front-loaded with the main action. No fluff 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?

With no output schema or annotations, the description is the sole source of behavioral context. It covers the high-level operation but lacks guidance on prerequisites, idempotency, return values, or potential side effects of running a mutating operation.

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% for both parameters (force and project_dir), so the description does not need to compensate. The description itself adds no parameter semantics beyond the schema.

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

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

The description clearly states the tool's function: 'Scan the project codebase and populate the knowledge graph with entities and relationships from existing code'. It uses a specific verb (scan/populate) and resource (codebase, knowledge graph), distinguishing it from siblings like query_fact (query) or record_event (record).

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?

Usage is implied by the tool name 'seed_project' (initial population), but the description provides no explicit when-to-use guidance or alternatives. No mention of when to run this versus other ingestion tools like ingest_pr_reviews or record_event.

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 the full burden of behavioral disclosure. It only states what the tool projects but does not indicate whether it is read-only, whether it requires specific permissions, or what outputs to expect. The lack of any side-effect or limitation details is a significant gap.

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

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

The description is a single, compact sentence that front-loads the core action and object. Every word contributes meaning, and there is no redundancy or filler.

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 and no annotations, the description should explain what the tool returns or how the output should be interpreted. It does not, and it also omits any caveats or prerequisites. For a simulation tool, this leaves the agent without enough context to use it confidently.

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 0%, and the tool description adds no parameter-level detail. The parameter names 'file_path' and 'change_description' are somewhat self-explanatory, but the description does not clarify expected formats, relationships, or how they map to the 'proposed change' concept, so it fails to compensate for the schema gap.

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 ('Project') and resource ('blast radius and historical outcomes for a proposed change'), making the purpose clear. It does not explicitly distinguish from sibling tools like 'predict_regression' or 'validate_change', but the focus on blast radius and historical outcomes is distinctive enough for a 4.

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?

No guidance is provided on when to use this tool versus alternatives. There is no mention of conditions like 'use when you need to assess impact before applying a change' or references to sibling tools, leaving the agent to infer usage context.

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 are provided, so the description must disclose behavioral traits. It only states the validation intent but doesn't explain whether validation is read-only, what happens on failure, whether it modifies anything, or what 'known constraints' refers to. This lack of transparency for a tool that could have side effects is a significant gap.

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 one short sentence that gets to the point. However, at 8 words, it is extremely terse and could have expanded to include usage context without becoming verbose. It is efficient but slightly under-specified.

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 there is no output schema and no annotations, the description should explain what the validation result looks like and when to use the tool. It only provides the core purpose, missing critical context about return values, behavior on constraint violation, and relationship to other constraint-related tools.

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 input schema covers 33% of parameters with descriptions (only proposed_content). The tool description does not mention file_path, change_type, or explain the enum values. It adds no semantic value beyond the schema, leaving file_path and change_type under-specified.

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 uses a specific verb 'validate' with a clear object 'proposed code change' and scope 'against known constraints,' which distinguishes it from sibling tools like simulate_change (which implies running a simulation). It clearly states what the tool does.

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 the tool is used for checking changes against constraints, but it does not explicitly state when to use it over simulate_change or how it relates to get_constraints. No alternatives are named, and no when-not-to-use guidance is given.

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 carries full burden. It discloses the independent Coach LLM call, the confidence levels (HIGH/MEDIUM/LOW), the verified and unverified claim lists, per-claim source_pointers, and that it never raises (failures return LOW with error populated). This is excellent 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?

The description is concise and front-loaded with the core purpose, followed by behavior and return details. The version tag 'v0.12.12' adds minor noise but does not detract significantly. Overall, every sentence earns its place.

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?

Since there is no output schema, the description fully explains return values (confidence, claim lists, source_pointers) and error behavior. It is complete for a verification tool, covering what the agent needs to know to invoke it correctly and interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add parameter-specific semantics beyond what the schema already provides; it references 'supplied source facts' but leaves parameter details to the schema. This is adequate but not additive.

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: 'Adversarially verify an answer is grounded in a specific set of facts.' It clearly distinguishes the tool from sibling tools like query_fact or validate_change by emphasizing adversarial verification against supplied source facts.

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

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

The description gives clear context for when to use this tool: whenever an answer needs to be checked against a set of facts. It implies the use case without explicit exclusion or alternative reference, but the context is strong enough to guide selection.

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