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

The annotations already cover the safety profile (destructive=true, openWorld=true, not idempotent), so the description doesn't need to repeat it. What the description does add is valuable: the result may leave the configuration 'active' or 'staged for operator approval', so the agent learns that this call may not take effect immediately and may need human approval. It also warns about the ordering of credentials. It does not say which permissions are required or how the destructive behavior manifests, so it is one step short of 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 short sentences, front-loaded with the core action, and each one adds a distinct fact (format rule, result semantics, status option). There is no filler, though the status hint could be folded into the earlier sentence for better flow.

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?

Because there is no output schema, the description must explain the return value, and it does so partially by mentioning the active-versus-staged outcome. However, for a destructive, open-world import with 0% schema coverage on five parameters, critical facts are missing: the meaning of connector_key and label, the purpose of base_url, and any hint about what the connector_key must be unique against.

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?

With schema coverage at 0% for 5 parameters, the description must carry the weight. It explains openapi_url (a public JSON URL, not YAML) and connection_status (the not_connected option for importing before credentials exist), which is genuinely useful. It says nothing about connector_key, label, or base_url, leaving the two required parameters and one optional field undocumented in both the schema and the prose.

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 and resource: import a public OpenAPI JSON URL as a connector. It defines the input format (JSON only, YAML must be converted), which sharpens the scope. It never distinguishes itself from the sibling create_connector, so the agent can't tell which is the right entry point from the description alone.

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?

There are clear constraints: the spec must be a public URL and JSON, not YAML, and connection_status=not_connected is the option for importing before credentials exist. However, there is no explicit statement about when to choose this tool over the sibling create_connector, or about preconditions or side effects. The guidance is implied by the constraints rather than stated as a rule for when to use the tool.

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