beel_create_company

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

With only `readOnlyHint=false`, `openWorldHint=true`, `idempotentHint=false`, `destructiveHint=false` given, the description carries the behavioral burden and pays it generously. It discloses ownership semantics (NIF registered under the account holder, never the caller), side effects that never happen (never switches an existing company on, never opens a checkout on 402), activation/seed behavior, idempotency-collapse behavior, and environment aliasing. This substantially exceeds what annotations alone communicate, with no contradiction against them.

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 long, but the tool is complex and every sentence earns its place — purpose is front-loaded, then side effects/errors, then guardrails are explicitly demoted to pointers rather than inline duplication. The ⚠️ block is a good structural device. It borders on dense but stops short of redundant; the only mild criticism is that some error detail (e.g., specific error codes) is repeated between the prose and the schema $defs.

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?

Despite the absence of an output schema, the description is remarkably complete for a tool this complex. It covers the create-vs-activate distinction, series seeding with per-environment isolation, billing and ownership consequences, all relevant error codes, idempotency behavior, and points to documentation resources for exhaustive rules and worked examples. Nothing an agent needs to call it correctly is missing; the docs pointers appropriately defer the long tail.

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 67% and the schema's nested $defs (Address, TaxInfo, CompanyNumbering, Environment) are richly self-describing, so the baseline is at least 3. The description layers real semantic value on top: it explains the activate/numbering coupling, that `aeat_environment` is ignored when `activate: false`, the idempotency_key collapse semantics, and the backwards-compatibility alias for the old field name. A strong addition, though the deepest parameter detail still lives in the schema itself, which is appropriate.

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 opens with a specific verb, resource and scope: "Creates a company (NIF) under the account in the path" — then immediately separates the two distinct acts of creating the profile and activating it, and names what activation seeds (three default invoice series). Endpoint is given explicitly. This clearly distinguishes it from siblings like beel_create_customer, beel_create_series, and beel_create_invoice, so an agent can tell it apart without inspecting those schemas.

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?

Usage context is explicit and actionable. It names the alternative door for switching an existing NIF on (`POST /v1/companies/{company_id}/activations`), states when a `numbering` block is rejected (`activate: false` → `NUMBERING_REQUIRES_ACTIVATION`), enumerates the error conditions (409 for existing NIF, 402 without billing), and routes to `beel_docs_search` for exhaustive rules via the fiscal guardrails block. Both when-to-use and when-not-to are covered.

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