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

Annotations already declare a safe, read-only, idempotent, closed-world operation, so the bar is lower, but the description still adds the crucial behavioral fact that it does not scan or connect to any network and works only from user-reported answers. It also describes what the returned card contains. It stops short of explaining scoring weights or confidence, which keeps it at 4 rather than 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?

It is front-loaded with the use case, then the returned content, then the exclusions, and the quoted user phrasings make the trigger conditions concrete. The paragraph is long and dense with many quoted examples, which is slightly more than strictly needed, but each sentence contributes selection or behavioral 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 12-parameter tool with no output schema, the description covers the input contract (fill from user statements, unknown/null otherwise), the return payload (score, signals, per-activity advice, visibility, checklist), and the hard boundary (no scanning or connecting). Nothing an agent needs to select or call it correctly appears to be 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 83% schema coverage the schema already carries most parameter meaning, so the baseline is 3; the description earns an extra point by instructing the agent to fill in only what the user actually said and to use "unknown" or null instead of guessing, which is real guidance the schema does not encode. It does not explain individual fields beyond that.

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 analysis task (assessing public Wi-Fi risk from what the user reports) and states the concrete output: a 0–100 score, the signals behind it, per-activity advice, a who-can-see-what breakdown and a venue checklist. It also distinguishes itself from the sibling secure_my_wifi by excluding home Wi-Fi and hack worries.

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 explicit trigger phrasings ("is hotel wifi safe", "does incognito hide my browsing"), lists the situations that select this tool (about to join or already on hotel/airport/café/campus Wi-Fi), and names exclusions with routing: home Wi-Fi and hack worries go to secure_my_wifi, and it must not be used for product recommendations, monitoring others, or unauthorized access.

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