Diagnose env setup

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

Annotations only say read-only/open-world/idempotent/non-destructive; the description adds the operational payoff — checks reported as pass/warn/fail with remediation hints — and critically explains that a healthy install always emits some warnings, preventing the agent from misdiagnosing a clean setup as broken. It also openly reconciles the readOnlyHint with the opt-in `probePin`: the one transient write (a tiny pin added then removed), so the agent knows the safety profile holds unless it sets that flag.

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 read-only framing and the failure-diagnosis purpose are front-loaded, and every clause (check list, pass/warn/fail, advisory warnings, the write exception) carries distinct information. It is dense with em-dash chaining rather than wasteful, though splitting the check list from the warning caveat would scan slightly faster.

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 compensates by describing the return shape (per-check pass/warn/fail plus remediation hints) and the meaning of the warning state. For a zero-required-parameter diagnostic tool, nothing an agent needs to call it or interpret results 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?

Schema description coverage is 100% and both parameters are already documented, including the HTTP 403 trigger and "added, then removed" for `probePin`. The description's contribution — restating that `probePin` is the sole write — largely overlaps the schema, so it adds only marginal meaning beyond the structured 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?

"Diagnoses env setup — the cause and the fix of an env-related failure" names a specific verb (diagnose) and resource (environment/setup), then enumerates exactly which subsystems are checked (RPC, Pinata, IPFS gateway DNS, subgraph, backend). An agent can distinguish this as the troubleshooting/diagnostic tool from the config-reading or context-fetching siblings without inspecting 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?

It gives a concrete trigger for the optional behavior — set `probePin` when an IPFS upload fails with HTTP 403 — and warns that warnings are advisories rather than failures, which is real decision guidance for the agent. What's missing is an explicit statement of when to reach for this over dexe_get_config or dexe_context, so the routing guidance is context-derived rather than spelled out.

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