get_guide

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds meaningful behavioral context on top: it makes no controller call (so no live state changes or network dependency) and it discloses the fallback behavior for omitted or invalid topics. It stops short of describing content depth or size per topic.

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?

Two sentences, front-loaded with the key distinction (static, no controller call) before the usage detail. Minor redundancy in re-enumerating all six topic names already present in the schema, but the structure is tight and skimmable.

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 carries the return-value burden, and it does indicate the two response shapes (an index vs. full topic content). It could say more about what a topic's content covers or its approximate size, but for a one-parameter static lookup this is close to complete.

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 the schema already documents the optional topic parameter, the six valid values, and the omitted/unrecognized fallback. The description largely restates that same list, adding no format or semantic detail beyond the schema, so the baseline 3 applies.

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 (Returns) and resource (static reference guidance on this server's S2 NetBox domain knowledge), and immediately distinguishes itself from the many controller-calling siblings by noting 'Makes no controller call.' An agent can tell this is a local knowledge lookup, not a data fetch, without opening a 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?

Explicitly covers both invocation modes: no topic returns an index, a topic set to one of the six named values returns that topic's content. It also flags the non-obvious fallback for unrecognized topics, which is exactly the kind of when/when-not guidance that prevents misuse.

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