identity_get_paged_service_definition_orgs

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds real value beyond that: deprecation status, the semantic caveat that all orgs have access, and a role-by-role authorization table. It omits pagination behavior and return shape, so not a 5.

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?

Front-loads DEPRECATED and the purpose, which is good, but then spends a four-row markdown table plus a raw endpoint line on a simple deprecated GET. Some of that content earns its place (the deprecation and access caveat), while the table and URL restate what annotations/schema already convey.

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 deprecated paged read with no output schema, the description should at least sketch what a page contains and how paging terminates. It covers authorization and deprecation well but leaves pagination and response shape unexplained.

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 only 33%: pageLimit and pageStart have no descriptions anywhere, and the description never explains pagination (defaults 128/0, ordering, next-page behavior). Only serviceDefinitionId is implied via the path template, so the description fails to compensate for the coverage gap.

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: 'Get organizations with access to specified service,' plus the deprecation flag and the raw endpoint path. It does not explicitly distinguish itself from near-siblings like identity_get_all_by_org_service_definitions (the inverse direction), so the reader must infer the distinction.

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 DEPRECATED tag plus 'This API has no analogue in Tenant Manager. Currently all organizations have access to all of the service definitions' tells the agent the result is effectively uninformative and the tool should be avoided. The embedded Access Policy table makes the required caller role explicit. It names no direct alternative tool, keeping it from a 5.

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