Moltline Code Review

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that every call is read-only and idempotent, discloses error behavior (never raises protocol error, returns descriptive error object), and notes the output is a confidence signal, not definitive proof. No contradiction with annotations.

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

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

Front-loaded with purpose, then enumerates smells, IO format, usage guidance, and error handling. Every sentence adds value; no fluff. Efficiently structured for an agent to quickly 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?

Given the output schema exists (context signals indicate present), the description still outlines return format ('reviewed_confidence', 'hits', etc.) and error format. Covers input, output, behavior, and error handling completely for a single-parameter tool with good annotations.

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 the single 'code' parameter. The description adds context: 'paste the file contents as a single string', provides typical input format, and explains what the tool looks for (list of smell types), going beyond the schema's basic 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 clearly states the tool flags indicators of unreviewed AI-generated code in a source file, lists specific smells (e.g., placeholder TODOs, over-broad try/except), and distinguishes from sibling 'review_diff' by stating it is not for diffs.

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

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

Explicitly says 'Use on a full source file suspected of unreviewed machine authorship. Not on a diff (review_diff)', and clarifies the result is a signal, not proof. Also explains error handling: never raises protocol error, returns an error object, so it is safe to retry after fixing input.

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

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

Annotations already provide readOnlyHint: true and idempotentHint: true. The description adds important context: 'Every call is read-only and idempotent', and details the error format ('returns {"error": ...}') and retry advice. Since annotations already handle the behavioral safety profile, the description earns a high score for supplementing with error-handling specifics without contradiction.

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

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

The description is tightly written with no wasted sentences. It front-loads the core purpose in the first line, then provides example input/output, usage guidance, sibling differentiation, error handling, and behavioral notes—all in a compact, well-structured paragraph.

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

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

Given the tool's complexity (2 parameters, clear output schema, strong annotations), the description is nearly complete. It covers purpose, usage, error behavior, and idempotency. Minor omission: it doesn't mention the output schema return shape beyond the example, but the presence of an output schema in the context signals reduces the need.

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 high (100%) for the two parameters. The description adds some semantic context beyond the schema by showing a typical input example ({"code": "<file contents>"}), but does not provide additional detail beyond what the schema describes for each parameter. Baseline 3 is appropriate as schema already handles the burden.

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

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

The description explicitly states 'Report structural complexity of a source file, function by function', with a specific verb ('report') and resource ('complexity of a source file'). The detail on what metrics are measured (length, nesting depth, branch count) and the flagging behavior clearly distinguishes this from siblings like 'security_deep_dive' or 'ai_code_smell_scan'.

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

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

The description gives explicit guidance: 'Use when structure rather than correctness is the question. Not for vulnerabilities (security_deep_dive).' It also explains error behavior and retry safety, helping the agent decide when to invoke this tool and when to choose an alternative.

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

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

Goes well beyond annotations: specifies error handling (never raises protocol error, returns error object), return format, idempotency, and read-only nature. No contradiction with annotations.

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

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

Well-structured and front-loaded. The persona description (skeptical, specific, kind) is slightly verbose but adds context. Could be trimmed without losing clarity, but still effective.

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

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

Given 0 parameters, existing output schema, and sibling list, the description covers purpose, usage, behavioral traits, return format, error handling, and differentiation. Nothing significant is missing.

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?

With 0 parameters and 100% schema coverage, baseline is 4. The description adds value by stating 'Takes no arguments' and explaining error behavior for invalid input, which is relevant beyond the empty 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 loads the 'Senior Reviewer persona' for consistent reviews. It distinguishes itself from sibling tools by explicitly saying 'Not for running a review - the scan tools do that.'

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

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

Provides explicit when-to-use ('keep repeated reviews consistent'), when-not-to-use ('not for running a review'), and alternatives ('scan tools'). Also mentions retry safety and license (PREMIUM).

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

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

The annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds valuable context beyond that: it explains the error behavior ('never raises a protocol error — it returns {"error": ...}'), confirms safety for retry, and notes it is free to use ('FREE'). This fully discloses the tool's 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 remarkably concise at three short paragraphs. It front-loads the key purpose and a notable feature ('FREE.'), then efficiently covers usage, alternatives, error handling, and safety. Every sentence adds distinct value 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?

Given the tool's simplicity (1 optional parameter, no required fields) and the presence of both input and output schemas, the description is complete. It explains the expected input, the output structure (with a concrete example), error handling, and fallback behavior. There are no missing elements needed for an agent to use this tool correctly.

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

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

Schema coverage is 100%, so the schema already documents the 'language' parameter well. The description adds value by giving a concrete example of the input and returned structure, as well as explaining fallback behavior for unknown values. The baseline is 3; the additional context justifies a 4.

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

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

The description starts with a specific verb ('Produce') and a clear resource ('pull-request review checklist'). It explicitly distinguishes itself from sibling tools like 'review_diff' and 'security_deep_dive' by clarifying its role is to guide the reviewer on what to look for, not to analyze actual code.

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 usage context: 'Use before a review, to decide what to look for.' It also explicitly states when not to use this tool ('Not for reviewing actual code') and names specific alternatives ('pass code to review_diff or security_deep_dive'). This gives the agent clear decision 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's job is to add context beyond those. It explicitly states 'Every call is read-only and idempotent,' which reinforces the annotations. More importantly, it details error behavior ('never raises a protocol error — it returns {"error": ...}') and describes the scanning scope ('Only added (+) lines are scanned'), which are behavioral traits not captured by annotations. A slight deduction because it does not mention any rate limits, cost implications, or auth requirements, though for a non-destructive, free tool this is minor.

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 compact (about 10 sentences) yet rich in information. It front-loads the core purpose in the first line, then efficiently covers scope, risk patterns, example usage, when-to-use vs not, and error behavior. No sentence is wasted — each adds distinct value. The use of bold and bullet-like lists in the output format description enhances readability without extra 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 tool has only 1 parameter with 100% schema coverage, comprehensive annotations, and an output schema (evident from detailed output description), the description covers all important aspects: purpose, sibling differentiation, error handling, idempotence, and input constraints. The only minor gap is that it does not explicitly list all supported output fields individually, but the output schema presumably handles that. For a tool of this complexity, no additional context is needed.

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% with a single required parameter 'diff' described as 'A unified diff exactly as produced by git diff — text with @@ hunk headers and +/- line prefixes. Only added (+) lines are scanned.' This is already quite complete. The description adds value by showing a typical usage example ('{"diff": "<git diff output>"}') and explaining how only added lines are scanned, which augments the schema description. It could be a 5 if it also described optional parameters or edge cases in input formatting.

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 starts with 'Risk-scan a unified diff the way a senior reviewer triages a PR,' providing a specific verb ('risk-scan') and resource ('a unified diff'). It clearly distinguishes this tool from siblings like complexity_report and ai_code_smell_scan by focusing on changes only and listing specific risk patterns it flags (injection sinks, disabled TLS, etc.). The description also explains what input is expected and what output format to expect, leaving no ambiguity about its 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?

The description gives explicit guidance: 'Use on a unified diff, when only the change matters.' It directly states when not to use it ('Not for whole-file analysis') and names two sibling alternatives (complexity_report, ai_code_smell_scan) for those scenarios. Additionally, it explains error handling ('never raises a protocol error — it returns {"error": ...}') and safety profile ('read-only and idempotent, safe to retry'), which informs proper usage patterns.

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 comprehensive annotations (readOnlyHint, idempotentHint, destructiveHint) already declaring safe read-only/idempotent behavior, the description adds important nuance: pattern-based detection, never echoes matched values, clean result is not proof, errors return structured messages rather than protocol errors. This provides behavioral context beyond annotations. The only small gap: does not mention rate limits or auth requirements.

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 packed with useful information but could be slightly more structured. Front-loaded with purpose, then free cost, then behavior/limitations, then error handling/safety. Every sentence adds value. Minor length is justified given the number of important behavioral clarifications.

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

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

Given the complexity (security tool with caveats), single non-enum parameter, and the presence of an output schema, the description covers: purpose, input format, output structure, limitations, error behavior, safety properties, and alternatives. Could be improved by listing a concrete example value for the type field categories.

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

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

Schema coverage is 100% with a single parameter, so the schema already documents the parameter. The description adds value by providing a concrete example input/output format, stating what kind of string to pass (file, diff, or config contents), and clarifying the result structure. This goes beyond the schema's minimal type 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 clearly states the tool scans text for accidentally-committed machine credentials and private-key material, specifying verb 'scan', resource 'text', and purpose. It distinguishes from sibling 'security_deep_dive' by explicitly noting this is not a general security review.

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

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

Provides explicit when-to-use context (scanning for leaked credentials), what it does not replace (not proof, needs human confirmation, not a general security review), and explicitly names the alternative sibling tool 'security_deep_dive'. Also tells the agent it is safe to retry after correcting input errors.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces these with 'Every call is read-only and idempotent' and expands on error behavior: 'never raises a protocol error — it returns {"error": "..."}'. This adds practical behavioral context beyond the annotations, covering safety and error handling.

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 structured in clear, well-organized paragraphs: purpose, capabilities, output format, usage guidance, and error behavior. Every sentence adds meaningful information without redundancy. Despite being multi-paragraph, it is efficiently front-loaded with the core action and quickly orients the agent.

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 a single parameter and an existing output schema, the description covers all necessary aspects: input format, output structure (with example), error handling, usage constraints, and safety guarantees. The mention of OWASP classes and fix direction provides a clear picture of what the tool returns. No gaps are evident.

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 only one parameter, 'code', with 100% schema description coverage. The description adds meaning by providing a concrete example of typical input ('{"code": "<file contents>"}') and clarifies that the input expects 'Full source text to audit, pasted as a single string; any common language.' This goes beyond the schema's brief description by giving usage context and format expectations.

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

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

The description explicitly states the tool runs an 'OWASP-oriented security pass over a source file' and lists specific vulnerability categories (injection, auth, crypto, SSRF, file handling). It distinguishes from siblings by noting it is not for 'style or structure (complexity_report)' and implicitly differentiates from secret_scan and ai_code_smell_scan. The verb-resource combination is clear and specific.

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 advises 'Use on one source file when vulnerabilities are the question' and explicitly states when not to use it: 'Not for style or structure (complexity_report), and never a substitute for a security professional on high-risk code.' This provides clear context for tool selection and excludes alternative uses, giving the agent actionable guidance.

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