Find Dead Code

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

Annotations already carry read-only/idempotent/non-destructive, and the description goes well beyond them: it discloses the 200-item cap, that a listed candidate is only a suspect rather than proof, the exact exemptions (framework attributes, partial methods, Designer/generated files, static Main, PrintMembers, ShouldSerialize/Reset), which caller scenarios are not measured, and how to read an empty result against methodsIneligible. That is rich behavioral context rather than a restatement of the hints.

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-loads the purpose and organizes the body by axis, exemptions, then return shape, so the structure is sound. It is nonetheless dense and uses long run-on sentences (the eligibility/exemption sentence in particular), which costs some readability even though most sentences carry distinct 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?

There is no output schema, so the description must carry the return contract, and it does: it names every returned field (scope, note, methodsScanned, deadMethods, typesScanned, deadTypes), the per-item shape, the counters and their zero-omission behavior. Combined with the exemption rules and the semantics of an empty result, an agent has enough to invoke and interpret the 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 description coverage is 100%, so the schema already documents kinds, scope, sessionId and includeTests; baseline is 3. The description adds only marginal meaning beyond that — notably that an empty answer without a note implies an eligible population was judged, and that any other non-blank kinds value runs both axes — while not adding scope syntax or sessionId behavior beyond what the schema states.

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 ('List dead-code suspects') and enumerates the two distinct axes it operates on (types with no incoming reference vs. private methods with empty caller lists). It also names the related sibling 'find_usages' as the source of the reverse type fan-in, letting an agent place it relative to siblings without opening the schema.

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

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

Gives clear selection guidance for the `kinds` axis, states the default (method), explains when to widen to 'all', and documents that test projects are excluded by default and what happens when other kinds values are passed. It does not, however, explicitly contrast the tool against plausible alternatives such as coverage_gaps or impact_of_change for a 'is this safe to delete' decision.

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