import_sources

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

No annotations are provided, so the description carries the full burden. It describes the read-only nature implicitly (returns available sources/types, no mutation implied) and lists concrete example values, which is helpful. However, it doesn't disclose details like pagination, whether results are company-specific vs global, or response shape/structure, and the return format is unspecified since there's no output schema.

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 a single focused sentence that conveys purpose plus concrete example values, with no wasted words. It front-loads the core purpose then provides enumeration details. Could be slightly tighter but is appropriately sized for a simple lookup tool.

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?

This is a low-complexity tool (1 optional param, no output schema, no nested objects), so the requirements are modest. The description covers the core purpose and example return values adequately. However, without an output schema, the agent cannot know the exact response structure, and the description doesn't reveal whether the returned data is company-specific (tied to companyId) or global, which is a meaningful gap given the one parameter.

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% for the single optional companyId parameter, which has a clear description ('Company UUID override (uses active company if not set)'). The description mentions the tool returns import sources/types but doesn't add meaning about how companyId affects the result set, though with only one well-documented parameter this is acceptable. No additional parameter meaning is needed 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 clearly states the tool's verb+resource (get import sources) and explicitly enumerates the specific import sources (SmartBill, Saga, Oblio, FGO, Facturis) and import types (clients, products, invoices_issued, etc.), which makes the purpose very concrete. It distinguishes from the broader import_* sibling tools (import_preview, import_execute, etc.) by being the enumeration/introspection endpoint, though it doesn't explicitly name them as alternatives.

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 implies this is a discovery/lookup tool for enumerating what import sources and types are available, which distinguishes it from the actual import execution tools (import_execute, import_upload, import_preview). However, it doesn't explicitly state when to use it vs. those alternatives, nor give guidance on what precedes it in a workflow (e.g., 'call this before import_upload to know supported types').

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