get_invoice_client_profilePer-company invoicing defaults (payment terms, delivery channel, custom invoice prefix). Returns {profile: null} when the company has none - profiles are created lazily.
| Name | Required | Description | Default |
|---|---|---|---|
| company_id | Yes | Company UUID (use list_companies to resolve). |
| Name | Required | Description | Default |
|---|---|---|---|
| profile | Yes | The company's billing profile, null when none exists yet. |
Changes observed during successful MCP inspections.
Input schema / properties / company_id / descriptionAdded value: +"Company UUID (use list_companies to resolve)."Output schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": false,
+ "properties": {
+ "profile": {
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "company": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Company name, null when not resolvable."
+ },
+ "company_id": {
+ "description": "Company UUID.",
+ "type": "string"
+ },
+ "delivery_channel": {
+ "description": "Delivery channel: Email, e-Invoice or Manual.",
+ "type": "string"
+ },
+ "id": {
+ "description": "Profile UUID.",
+ "type": "string"
+ },
+ "invoice_prefix": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Custom invoice number prefix, null for the tenant default."
+ },
+ "payment_terms": {
+ "description": "Payment terms: Net-15, Net-30, Net-60, Net-90 or Due on Receipt.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "company_id",
+ "company",
+ "payment_terms",
+ "delivery_channel",
+ "invoice_prefix"
+ ],
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The company's billing profile, null when none exists yet."
+ }
+ },
+ "required": [
+ "profile"
+ ],
+ "type": "object"
+}Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses that profiles are created lazily and returns {profile: null} when none exists. This adds behavioral context that is not present in the annotations or schema, helping the agent anticipate edge cases without contradicting the annotation.
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 front-loads the core purpose and then adds the null-return nuance in a second short sentence. There is no redundant information, and every phrase contributes to understanding the tool's behavior.
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?
With only one parameter, a clear output schema, and the description covering the null case and lazy creation, the tool is fully specified for an agent to call correctly. The description adds essential context (lazy creation) that is not inferable from the schema or annotations, making it complete.
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?
The schema provides 100% coverage for company_id, including a description referencing list_companies for resolution. The description does not add any extra parameter-specific semantics beyond what the schema already documents, so a baseline score of 3 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 clearly states the tool retrieves per-company invoicing defaults (payment terms, delivery channel, custom invoice prefix), which is specific and distinct from sibling tools like get_company or get_invoice. It also clarifies the return value when no profile exists, removing ambiguity about behavior.
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 usage for reading invoicing defaults per company but does not explicitly contrast with alternatives such as upsert_invoice_client_profile or delete_invoice_client_profile. While the context suggests it is the read-only counterpart, the description lacks explicit when-to-use or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.