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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful context beyond that: the data derives from 'code_review ApiEndpointDiscovery' and that omission of scan_id yields the whole company — a behavioral scoping fact not present in the annotations.

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 compact sentences/fragments that are front-loaded with the resource and its contents before the scoping note. No filler, though the trailing 'Reads code_review ApiEndpointDiscovery' is somewhat terse and slightly under-explained.

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?

With no output schema, the description carries the burden of describing returns, and it does — endpoints, auth status, risk level, factors, and breakdowns. Combined with annotation-covered safety and a fully documented two-param schema, an agent has nearly everything needed to call it correctly; only explicit sibling routing is absent.

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%, so both limit and scan_id are already documented in the schema. The description only restates the scan_id omission behavior ('company-wide if omitted'), adding no new semantic detail beyond the structured field. Baseline 3 is appropriate.

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 concrete verb+resource (API security inventory of discovered endpoints) and enumerates the payload: authentication status, risk level, risk factors, and method/risk breakdowns. That level of specificity lets an agent distinguish it from generic sibling tools like get_insights or compliance_status.

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 description explains the scoping choice — 'Company-wide or one scan with scan_id' — which is real usage guidance for the parameter. However, it never names an alternative tool or states when this inventory is preferable to a related sibling (e.g., compliance_scan, get_cloud_compliance), so usage is only implied.

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