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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is known. The description adds non-obvious behavioral details: presets are included in results but never count in summary.total (CO 455), and the same call works recursively at any depth. This goes beyond annotations and adds valuable context, though it doesn't discuss rate limits or edge cases, which are less critical given the read-only nature.

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 long but every sentence carries substance. It is front-loaded with the core purpose, then systematically covers sides, presets, parent navigation, and the sibling relationship. It also includes a concise example call and return format. While it could be trimmed slightly (e.g., the CO 455 reference may be unnecessary), the organization and density are strong for a tool with this complexity.

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?

Despite having only 2 optional parameters, the tool's behavior is complex: recursive catalog, side filtering, presets, and interactions with sibling tools. The description adequately explains all these aspects, including explicit return structure ({ platforms: [...], summary: { total, side, parent } }), the exclusion of presets from totals, and the usage context. It provides a complete picture for an agent to use and interpret results correctly, and no output schema is needed because the description fills that gap.

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 100%, so a baseline of 3 is appropriate. The description enriches both parameters: it clarifies side='vendor' returns sell-on platforms (retail, bookings) and side='customer' returns run-tools (messaging, shipping), and gives concrete examples for parent (e.g., parent='messaging' returns email/sms/dm). It also implicitly explains the interaction (when parent is present, side is ignored, as noted in the schema). This adds meaningful usage context beyond the schema.

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 states a specific verb+resource: 'Browse the ComOS network's composable platforms as a recursive catalog.' It distinguishes from siblings by explicitly contrasting with federation_catalog_agents: 'platforms are what you become; agents are the operators you hire to run them.' Clear differentiation and precise scope.

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 provides explicit when-to-use guidance: it explains two modes (side for sell-on vs customer), how to navigate via parent, and notes that presets are not platforms. It also names the sibling tool and clarifies when to use each ('Pairs with federation_catalog_agents: platforms are what you become; agents are the operators you hire to run them.'). This gives clear context for choosing this tool over alternatives.

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