business_profile_create

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

No annotations are supplied, so the description carries the full burden. It usefully explains that these fields become the issuer and are validated by an e-invoicing ruleset, and it clarifies the conceptual boundary with a branding profile, but it says nothing about creation side effects, duplicate-name behaviour, error modes for invalid tax ids, or what the Idempotency-Key parameter does.

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 lead sentence is front-loaded and states the core identity of the tool immediately, followed by two short paragraphs that add scope and a useful disambiguation. Some lines are slightly discursive, but no sentence is redundant.

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 15-parameter creation tool with no annotations and no output schema, the description gives good conceptual framing but leaves large gaps: nothing about what is returned on success, which optional fields are actually required by common rulesets, or how the idempotency key should be supplied. It is adequate for an agent to understand intent, less so to call the tool confidently.

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 only 20% across 15 parameters, so the description has to compensate and does so only partially: it highlights legal_name, tax_id, address and bank details as the fields that matter for issuance and compliance. Many parameters — display_name, logo_file_id, default_locale, default_currency, default_timezone, Idempotency-Key, email, phone, website — get no treatment at all in the description.

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 and resource — 'Create an identity to issue documents as: the seller side' — and names the fields that constitute that identity (legal_name, tax_id, address, bank details). It explicitly separates itself from a branding profile, so an agent can tell what kind of entity is being created, though it never names the closer sibling business_profile_list as the alternative for reading existing profiles.

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 is implied rather than stated: you create this when you need to issue documents as a seller and the ruleset will check the issuer fields. There is no explicit when-not guidance, no mention of preconditions such as an existing profile, and no pointer to business_profile_list for inspection, so the agent must infer routing from context.

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