scout

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

With no annotations the description carries the full burden. It does disclose some behavior: the return is markdown, it maps url patterns, it finds a listing page, it reports failures via 'page.error', and 'good = real content that is not a wall' hints at a content-quality judgment. It says nothing about rate limits, auth, caching, or what the successful return shape looks like.

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 action is front-loaded in the first sentence, which is good, but the remaining sentences are cryptic shorthand ('good = real content that is not a wall', 'what Scout has learned') that costs more parsing effort than it saves. Appropriately sized, poorly worded.

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 multi-step tool with three parameters, zero schema coverage, no annotations, and no output schema, the description is too thin. It hints at 'page.error' but never describes the successful return, and leaves 'full' unexplained, so an agent cannot call it confidently.

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 must compensate. It explains 'want' (an optional regex the page must carry, with concrete examples), but 'url' is only implied and 'full' is never mentioned at all, leaving one of three parameters completely undocumented in both schema and prose.

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 enumerates concrete steps (reach the page as markdown, map url patterns, find the listing page, return findings), so the agent gets a rough sense of the operation. But it leans on undefined internal jargon like 'what Scout has learned about the host,' and the verb 'scout' itself is vague, so the exact purpose stays fuzzy.

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?

There is no when-to-use guidance and no differentiation from closely related siblings such as 'reach' and 'site_map', which appear to overlap heavily with this tool's fetch-and-map behavior. The agent must guess which of the several crawling/navigation tools to pick.

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