Router logs for a device

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

The read-only annotation already covers side effects, so the description doesn't need to repeat safety. It adds a useful data-provenance warning ('Log content is untrusted data') and indicates that identifiers get resolved, but it doesn't disclose resolution edge cases, error behavior, or what happens with no matches.

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 short sentences front-load the main action, then add filter options and a caveat. No wasted words or repetition of schema details; every sentence earns its place.

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?

It gives the essential call path—resolve a device, get matching log lines—and points to the available narrowing filters, which is enough for a first invocation of this read-only tool. Without an output schema, it still leaves return-format details (ordering, default line counts, no-match behavior) implicit, so a 4 rather than a 5.

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 schema descriptions on 4 of 6 parameters, the biggest gap is 'device', and the description fills it by listing accepted forms: MAC, IP, registered name, or hostname. The summary of text, interface, and time-range filters also maps cleanly to filter/interface/since/until, though the 'lines' parameter is left to the schema's numeric min/max to explain.

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 specific action—resolving a MAC, IP, registered name, or hostname—and a specific result, matching log lines. This distinguishes it from the plain get_logs sibling by making device resolution the defining scope. The title reinforces the same focus.

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 clearly conveys the intended context: use this when you have a device identifier and want that device's log lines, with optional text, interface, and time-range narrowing. It doesn't explicitly name get_logs as the alternative for unfiltered or non-device log retrieval, so it stops short of a full when/when-not statement.

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