Get broken internal links report

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds valuable behavioral context beyond those: coverage semantics (internal vs provider totals vs excluded external rows), the interpretation of HTTP 403 as access denied rather than missing page, and the security note that returned data is untrusted source content. These are non-obvious behaviors the agent needs to know to use results correctly.

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 description is concise (five sentences) and each sentence serves a purpose: the first defines the core action, the second clarifies data scope, the third explains crawl coverage limitations, the fourth addresses a common misinterpretation (403), and the fifth warns about untrusted data. No filler words; all content is actionable. It could be slightly tighter, but it is well-structured and front-loaded.

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?

Given the tool's simplicity (one parameter, no output schema), the description fully equips an agent to use it correctly. It explains what the tool returns, how to interpret the data, what to expect from certain HTTP statuses, and the trust level of the content. It also implicitly distinguishes itself from creation tools. There are no obvious gaps for the agent to resolve.

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?

The only parameter, reportId, already has a complete description in the schema (100% coverage), so the tool description does not need to add more. The description itself does not elaborate on the parameter beyond what the schema provides. Since schema coverage is high, a baseline of 3 is appropriate; no additional semantic value is added by the description for this parameter.

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 clearly states a specific verb ('Retrieve'), a specific resource ('internal link and resource checks'), and explicitly contrasts with re-running the crawl. It also distinguishes coverage semantics, making it distinct from sibling tools like get_backlinks_report or create_broken_links_report. The purpose is unambiguous.

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?

The phrase 'without re-running the crawl' implies this tool is for retrieving existing results rather than generating new ones, which aligns with the create/get pairing in sibling tools. The description does not explicitly name alternatives or state when not to use it, but the context (e.g., needing a reportId) and the caveat about crawl coverage provide reasonable usage guidance. A slight gap is not mentioning that the matching create tool must be run first, though that is implied by the parameter description.

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