get_agent_adoption_scan

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds meaningful behavior beyond that: the tool returns different payload shapes depending on run state and should be polled at a 5-10 second interval. It stops short of describing result contents or failure states.

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-loaded with the core action, and the polling recommendation lands last where an agent will find it. Sentence two partially restates sentence one's status-retrieval idea, a small redundancy.

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 must characterize return values, and it does distinguish the running-status response from the completed-results response. This is adequate for a one-parameter polling getter, though it says nothing about error or expired-scan behavior.

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 a single parameter at 100% schema coverage, the schema already carries the format detail (the 24-char hex pattern and the 'from start_agent_adoption_scan' origin note). The description restates that lookup is by scanId but adds no new syntax or constraint information, so 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 and resource ('Retrieve status or full results of an Agent Adoption Check by scanId'), which clearly separates it from the sibling start_agent_adoption_scan without needing to name it. It is not tautological and conveys the retrieval role precisely.

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?

Explains when in the lifecycle to call it ('while running' vs 'when finished') and gives a concrete polling cadence of 5-10 seconds, which is real operational guidance. It does not explicitly name the alternative tool for launching a scan, so it falls short of full when/when-not coverage.

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