Connect App

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

Annotations only declare openWorldHint=true and readOnlyHint=false, but the description adds substantial behavioral context: credentials go to vault never through chat (security), one-time browser URL flow, immmediate install for credential-less apps, portal activation behavior, and OAuth exclusion. This is rich behavioral disclosure beyond 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?

Three sentences covering all key behavioral aspects with no wasted words. Front-loaded with the core purpose first, then qualification branches. Every sentence adds information: core action, credential flow, credential-less flow, and OAuth exclusion.

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 tool with 2 params and no output schema, the description covers the main behavioral paths well: credentialed vs non-credentialed apps, portal activation, and OAuth limitation. Could note whether this is reversible (uninstall_app sibling exists) but given no output schema and moderate complexity, this is largely complete.

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 50% (only portalRef is documented in schema). The description explains portalRef's activation effect in the schema, and the description adds context about appKey (it's the app identifier). However, the description doesn't deeply elaborate on appKey validation or format beyond what's in schema. The description adds marginal value for the undecorated appKey param.

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?

Description uses specific verb+resource: 'Install and connect an app to its backend', clearly distinguishing this from sibling tools like install_app and uninstall_app. It covers the core action and the credential-handling nuance, though it doesn't explicitly contrast with the similarly-named sibling install_app.

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?

Clearly explains when to use it, distinguishing behavior for apps with credentials (one-time browser URL) versus without (immediate install). It also states OAuth apps are not connectable yet, providing an exclusion. However, it doesn't explicitly name alternative tools to route around, so it falls just short of a 5.

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