orgs_read

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, so safety is covered; the description adds the useful token-cost tradeoff between compact and full modes. It does not describe pagination behavior (page/pageSize) or what a compact record contains, which keeps it below 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?

Four tight sentences: capability, mode guidance, single-item shortcut, then boundaries. Front-loaded with the action list and free of filler.

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 read-only tool with no output schema and full annotation coverage, the agent knows which action to pick, what mode to request, and which sibling handles adjacent jobs. The only material gap is pagination semantics for page/pageSize, which neither schema nor description resolves.

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 coverage is moderate (57%), and the description compensates by explaining the compact-vs-full tradeoff, the default mode, and the get-vs-list preference. The schema itself documents mode, orgId, search, and agentId requirements, so only page/pageSize remain unexplained anywhere.

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 names the resource (organizations and related membership) and enumerates all seven supported actions, so the scope is unambiguous. It also names the sibling it is not (orgs_write for mutations, clients_read for end-user client accounts), letting an agent route without opening either schema.

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?

Explicit rules are given: list/search default to compact, use full only when complete objects are needed, prefer action=get for a single org. It also excludes writes and redirects to orgs_write, and redirects end-user client accounts to clients_read — both when-to-use and when-not-to-use are covered.

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