Apply a company import (legacy route)

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

Annotations already indicate it's not read-only (readOnlyHint=false) and not destructive (destructiveHint=false), but the description adds only an authorization class ('board_or_agent') and HTTP method, not behavioral details like side effects, whether it modifies existing data, or what the return value represents. For a mutation tool, more behavioral context is needed.

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 short (two sentences) but wastes space on internal metadata (Paperclip operation, authorization class) rather than agent-facing guidance. It is concise but not well-structured for agent consumption.

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?

Given the complex input schema with nested objects and many options, the description is insufficient. It does not explain the overall import process, prerequisites, or how to construct the 'body' parameter. The presence of an output schema does not compensate for missing operational context.

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 description coverage is 0%, yet the description provides no parameter explanations. It does not clarify the roles of 'source', 'target', 'include', or other nested fields, leaving the agent to guess from the schema structure alone.

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 'Apply a company import' but does not explain what 'apply' means in this context (execute a previously previewed import? perform an import from scratch?). It does not distinguish from sibling tools like pc_post_companies_import_preview or pc_post_companies_by_company_id_imports_apply, leaving the agent to infer the difference.

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?

No guidance on when to use this tool versus alternatives. The description only mentions it's a 'legacy route' but doesn't specify the preferred modern alternative or criteria for choosing this one.

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