find_paths_to

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so safety and idempotence are covered structurally. The description adds genuinely useful behavior beyond that: it discloses the reverse-traversal semantics, that results include the call chain, and that bare target names match every contract's function with that name — a non-obvious fan-out behavior. It omits pagination/truncation behavior when max_chars is hit, so not 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?

The definition is front-loaded: one sentence states the operation and direction, followed by illustrative questions, then a compact args block. Every line carries information — including the wildcard-matching caveat on bare target names — with no redundant restatement 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?

There is no output schema, and the description does indicate that returned results are entry points plus the call chain connecting them, which is the key return-value hint an agent needs. Combined with the parameter documentation, this is nearly complete for a read-only query tool; only the truncation behavior of max_chars and the depth/ordering of chains remain unspecified.

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 carries the full burden and does so well: it specifies the target grammar ("Contract.fn(types)", "Contract.fn", bare "fn") and the wildcard consequence of bare names, explains include_read_only as also searching view/pure entry points, and defines max_chars as an output size cap. These are meanings an agent could not infer from the bare schema property titles alone.

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 precise technical framing, "Reverse reachability: which entry points can reach a given function (or dependency call), and through which call chain," which names both the resource (call paths) and the direction of traversal. The two quoted example questions ("who can reach _mint?", "which external functions end up in Pool.swap?") make the operation concrete. It does not explicitly distinguish itself from siblings like get_flow or list_entry_points, which holds it back from a 5.

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 example questions function as clear usage cues: use this when you want to know what can reach a target, as opposed to forward traversal. The parenthetical "(or dependency call)" also signals the target can be a non-function node. However, there is no explicit statement of when NOT to use it and no named alternative for forward or entry-point listing tasks.

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