list_platforms

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

With read-only and idempotent annotations already present, the description adds meaningful behavior: direct OAuth URLs are intentionally not exposed, account_id wins over platform when both are given, include_planned reveals future integrations, and credential platforms show credential_fields needed by connect_account. It does not cover rate limits or response size, but it goes well beyond 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?

The description is front-loaded and information-dense, but it is a single run-on paragraph with semicolons and repeated platform examples that duplicate the schema enums. It is not bloated, but it could be structured more clearly for an agent to scan quickly.

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 complex seven-parameter, three-view tool without an output schema, the description explains what each view returns and the key constraints an agent needs to call it correctly. Minor gaps remain, such as not describing workspace_id behavior beyond the schema, but overall it is complete enough for correct invocation.

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 the baseline is 3, but the description adds precedence rules (account_id wins over platform), default behavior (view=platforms), intended use of connection_url, and guidance to omit target to list live connection targets. Workspace_id and debug receive less description-level explanation, but the added semantics are useful.

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 establishes that this tool retrieves platform metadata, settings schemas, and connection links, and breaks this down by view mode. It distinguishes the tool from siblings like list_accounts and connect_account by describing what each view returns, though the opening phrase is telegraphic rather than a full verb-led purpose statement.

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?

It gives clear usage context for each view: platforms is the default, schema is preferred with account_id and is needed before Instagram native tags/collaborators, and connect_link should use connection_url in a logged-in browser. It does not explicitly state when not to use the tool, but the view-specific guidance is strong.

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