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

With no annotations, the description carries the safety burden and does so by declaring the operation 'non-destructive, read-only diagnostic inspection', so the agent knows no state is mutated. It does not mention runtime cost, large dump handling, or what happens on a missing/corrupt dump, which keeps it from a 5.

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?

Three sentences, each earning its place: capability, when-to-use/when-not with named siblings, then behavioral/safety profile. Front-loaded with the core purpose and zero 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?

For a single-parameter diagnostic tool with no output schema and no annotations, the description covers purpose, routing, and safety. The one gap is it never indicates what the analysis yields (a text RCA report, findings list, etc.), which the absence of an output schema would otherwise require.

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

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

Schema coverage is 100% and there is only one parameter, so baseline would be 3. The description adds real meaning the schema lacks: the schema only mentions '.dmp', while the description extends acceptance to Linux ELF core dumps, resolving a potential ambiguity for the caller.

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

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

States a specific verb (performs automated Root Cause Analysis) on a specific resource (Windows .dmp and Linux ELF core dumps), and names the crash dumps / call stacks it targets. An agent can distinguish it from sharphy_deadlock_detector and sharphy_inspect_heap by name alone.

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 gives the positive condition ('diagnosing fatal process crashes, unhandled exceptions, or crashing thread call stacks') and the negative cases with named alternatives for each: deadlocks go to sharphy_deadlock_detector, leaks go to sharphy_inspect_heap. No inference required.

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 load; it discloses the mutation behavior and that output goes to outputPath, clarifying the input is not patched in place. Minor gaps remain (e.g., whether the original is preserved, permissions needed, or runtime cost), keeping it below 5.

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?

Three tight sentences, zero waste, with the core capability stated first followed by usage routing and the mutation note. Well front-loaded.

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 two-parameter tool with full schema coverage, the description covers purpose, selection guidance, and mutation semantics adequately. It does not mention what the tool returns or reports (no output schema exists), which is a small omission.

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

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

Schema coverage is 100% and both parameters are already documented with descriptions, so the baseline is 3. The description only restates the destination concept ('creating a cleaned assembly at outputPath') without adding format or constraint detail 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?

States specific verbs and resources: CFG demangling, dead-code trimming, NOP-sled trimming, and dynamic proxy delegate analysis, all targeting obfuscated assemblies. It also explicitly names the sibling it is not (sharphy_patch_il), letting an agent distinguish it without opening schemas.

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?

Explicit when-to-use ('when reverse engineering obfuscated assemblies') and when-not ('Do NOT use for direct opcode modification'), with the correct alternative named (sharphy_patch_il). Nothing is left to inference about 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 safety burden itself by declaring 'Non-destructive, read-only inspection,' which resolves the mutation question outright. It also describes the analysis approach (SyncBlock traversal, WFG construction), though it says nothing about expected runtime, dump-size limits, or the shape of the results an agent should expect.

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?

Three sentences, each doing distinct work: what it does, when to use it, when not to and what to use instead, plus the safety note last. Front-loaded with the core capability and free of 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?

For a single-parameter, read-only tool with no output schema and no annotations, the description covers purpose, usage routing, and safety adequately. The remaining gap is that it never hints at what the Wait-For Graph analysis returns (cycle participants, contention rankings), which would help an agent 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?

There is a single required parameter with 100% schema description coverage ('Absolute path to the target memory dump file (.dmp)'), so the schema already fully documents it. The description adds no further detail such as path constraints, supported dump formats, or whether the file must match the running analysis version, so baseline 3 applies.

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 names a specific verb and resource ('Detects thread synchronization deadlocks and lock contention') and discloses the mechanism (traversing CLR SyncBlocks, building a Wait-For Graph). It is clearly distinguishable from siblings like sharphy_inspect_heap and sharphy_analyze_dump, which are explicitly named as the wrong tools for adjacent jobs.

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 states the exact triggering condition ('diagnosing unresponsive or frozen .NET applications suspected of thread lock cycles') and gives explicit exclusions with named alternatives for exception crashes and heap analysis. Nothing is left to inference about when to pick this tool.

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

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

With no annotations, the description carries the behavioral burden and does disclose that this is read-only inspection and that it uses an embedded ILSpy engine. It does not explain failure modes for obfuscated code, dependency resolution, or potential output limitations, but the key safety profile is stated clearly.

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?

Three compact sentences, front-loaded with the action and engine, followed by usage guidance and exclusions. No sentence is wasted.

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 core operation, intended use cases, exclusions, and read-only nature, which is sufficient for an agent to invoke the tool correctly. It does not address handling of overloaded method names or decompilation failure cases, leaving a minor gap for a tool with three required parameters.

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

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

Schema description coverage is 100%, so the schema already documents assemblyPath, typeName, and methodName. The description adds no parameter-specific detail such as overload disambiguation or path constraints beyond what the schema provides, making the baseline 3 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?

States a specific verb and resource: decompiles CIL bytecode into idiomatic C# source code using ILSpy. It explicitly names sibling tools it is not for (sharphy_inspect_metadata, sharphy_diff_assemblies), so the agent can distinguish it without opening other schemas.

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

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

Provides explicit when-to-use guidance: inspecting method logic, lambda expressions, or async state machines. It also gives explicit when-not-to-use guidance and names the correct alternatives for metadata enumeration and binary diffing.

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 safety profile; it does declare 'Read-only comparison', which tells the agent this is a non-mutating operation. It also scopes the depth of analysis (metadata-level, not full method bodies). It does not mention behavior on invalid or non-.NET inputs, performance cost on large assemblies, or the shape of the comparison result, so a small gap remains.

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?

Three sentences, front-loaded with the core comparison semantics, followed by usage context and the exclusion. The middle sentence enumerating use cases is slightly redundant with the opening purpose statement, but every clause still contributes routing or scope 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?

For a two-parameter read tool with no output schema, the description conveys what the comparison yields (added/removed types, breaking changes, CIL size shifts), that it is read-only, and where the boundary lies versus decompilation. Only return format and error/precondition handling are left implicit.

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%: both oldAssemblyPath and newAssemblyPath are documented as baseline and updated paths respectively. The description adds no parameter-level guidance beyond implying the two versions are compared, which is the expected baseline when the schema does the work.

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

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

States a specific verb and resource (compares two compiled .NET assemblies) plus the precise comparison layer (ECMA-335 metadata) and the resulting signal types (added/removed types, API breaking changes, CIL instruction size shifts). It explicitly distinguishes itself from sharphy_decompile_method, so an agent can separate the two without opening either schema.

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

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

Names concrete usage contexts (validating library updates, regression testing, detecting API modifications) and pairs an explicit exclusion with the correct alternative: 'Do NOT use for decompiling full method bodies (use sharphy_decompile_method)'. When-to-use and when-not-to-use are both present.

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 and does well: it discloses the isolation model (collectible ALC), the key side-effect guarantees (no file locking, no host-runtime pollution) and the safety profile ('sandboxed read-only execution'). It stops short of describing failure behavior — e.g. what happens on dependency resolution or bad-image load errors — which matters for a tool that must actually execute assembly loading.

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?

Three sentences, each doing distinct work: what it does, when to use it, and when not to. The mechanism and the primary benefit are front-loaded, and there is 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?

For a single-parameter read-only tool with no output schema, the description covers purpose, selection criteria, and safety well. The remaining gap is the return shape — 'tokens and types' is vague about what the agent actually receives (token values, type names, resolution results), which the absent output schema would otherwise have supplied.

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 parameter 'assemblyPath', so the schema already documents it. The description adds no constraints beyond the schema — no notes on supported path forms, relative vs absolute paths, or whether the assembly's dependencies must be resolvable from that location. Baseline 3 applies.

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

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

States a specific verb and resource ('extracts runtime tokens and types') plus the mechanism ('loading target assemblies inside an isolated collectible AssemblyLoadContext'), which is far more precise than the tool name alone. It also explicitly distinguishes itself from the static-analysis sibling 'sharphy_inspect_metadata'.

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

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

Gives an explicit positive trigger ('use this tool when dynamically inspecting types without locking files on disk or polluting the host runtime') and an explicit exclusion with a named alternative ('Do NOT use for static disassembly... use sharphy_inspect_metadata'). The agent has everything needed to route between this tool and its closest sibling.

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 and does disclose the key behavioral trait: it mutates disk by writing a .cs file to outputPath, and it documents the .NET 8+ requirement and performance profile. It does not say whether an existing output file is overwritten, whether the target assembly is modified at all (it is not, but that's implied only), or what happens on invalid type names.

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?

Three sentences, each earning its place: capability, positive trigger, exclusion + side effect. The most decision-critical fact (disk mutation) is stated up front rather than buried.

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 non-read-only, no-annotation, no-output-schema tool, the description covers what it produces, where it writes, the framework requirement, and the sibling it replaces. Remaining gap is overwrite/error semantics for outputPath, which an agent would want before invoking blindly.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description only reinforces outputPath as a written .cs file; it adds no format or validity details (e.g. fully qualified name syntax, path restrictions) beyond the schema. Baseline 3 applies.

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

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

States a specific verb (generates) plus a precisely scoped resource (strongly-typed C# wrapper source using [UnsafeAccessor] with zero reflection), and contrasts itself against the sibling tool sharphy_patch_il. An agent can distinguish it from decompile_method or patch_il without opening any schema.

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

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

Gives an explicit positive trigger ('when testing or accessing inaccessible internal/private APIs') and an explicit exclusion with the alternative named ('Do NOT use for bytecode modification (use sharphy_patch_il)'). This is exactly the when/when-not/alternative pattern.

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 and does disclose the safety profile: 'Non-destructive, read-only inspection.' It does not mention prerequisites such as dump size limits, analysis duration, or behavior on an invalid/missing dumpPath, leaving some operational gaps for a heavy artifact-analysis 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?

Three sentences, front-loaded with the capability, then routing guidance, then safety. Every sentence earns its place with zero 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?

No output schema exists, but the description enumerates the kinds of findings returned (generation sizes, fragmentation, retainers), which partially substitutes. Minor gap: no indication of result volume or cost when analyzing a large dump.

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 both dumpPath and topObjects are already fully documented in the schema. The description adds no further parameter meaning (e.g., how topObjects interacts with output size or whether generation data is always returned), so the baseline 3 applies.

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

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

States a specific verb ('Inspects') plus a precise resource list — heap allocations, Gen 0/1/2/LOH/POH sizes, fragmentation, and leak retainers in a memory dump. This is clearly distinguishable from sharphy_analyze_dump and sharphy_deadlock_detector, which the description names.

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

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

Gives an explicit positive trigger (high memory usage, memory leaks, OutOfMemoryException) and explicit exclusions with named alternatives for crash RCA and thread lock cycles. An agent needs no inference to route between these siblings.

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 and does declare the safety profile ('Read-only inspection') plus a scope boundary (metadata only, no method bodies). What is missing is any statement about failure modes on bad paths or what the returned structure looks like, which matters since there is no output schema.

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

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

Three tight sentences: capability front-loaded, then usage condition, then exclusion. Every sentence carries distinct information with no repetition of the tool name.

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 single-parameter read-only inspection tool with no output schema, the description gives enough to select and invoke it, and the enumeration of table types implicitly signals the shape of results. A brief note on return structure or behavior on malformed/obfuscated assemblies would close the remaining gap.

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 is a single parameter and schema description coverage is 100%, with the schema already stating it must be an absolute path to a .dll/.exe. The description adds no further constraint or format guidance beyond that, so baseline applies.

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

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

States a specific verb and resource ('Decodes ECMA-335 metadata tables') and enumerates the concrete contents (TypeDef, MethodDef, FieldDef, custom attributes, P/Invoke imports, embedded resources). It also distinguishes itself from a sibling by contrasting with decompiling method bodies.

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

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

Gives an explicit when-to-use clause ('discovering types and member signatures of an assembly without decompiling method bodies') and an explicit exclusion routing to a named alternative ('Do NOT use for binary comparisons (use sharphy_diff_assemblies)').

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, so the description carries the full behavioral burden. It usefully discloses that it mutates by writing a patched assembly to outputPath (implying original preserved), but doesn't mention permissions, error handling for invalid offsets, or side effects on the source assembly. Partial disclosure 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?

Three tight sentences, front-loaded with the core action, then usage, then exclusion. Every sentence earns its place with no redundancy.

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

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

For a 6-required-param mutation tool with no annotations and no output schema, the description covers purpose and destination well but leaves error behavior and precise return value undocumented. Adequate but with clear gaps.

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

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

Schema coverage is 100%, so the schema already documents all six parameters. The description adds context by naming the mutation concepts (opcodes, branch targets, outputPath) but no syntax or format detail beyond the schema. Baseline 3 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?

States a specific verb+resource: modifies CIL bytecode by replacing opcodes, adjusting branch targets, emitting a patched binary. Explicitly distinguishes from the sibling 'sharphy_clean_obfuscation' as the non-target for this tool.

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?

Names concrete use cases (bypassing validation, inserting NOP sleds, altering execution flow) and an explicit exclusion routing to the alternative 'sharphy_clean_obfuscation'. When/when-not/alternative are all present.

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