Agent Tool Definition House Style

Contract

When you write a tool (function signature + docstring) that an LLM agent will call, or a prose line telling an agent which MCP tool to use, emit it in this exact house style. These are arbitrary conventions, not general advice — conform literally.

Rules

1. Tool naming

• The tool name is verb_noun in lowercase snake_case: get_customer,

create_order, cancel_subscription, refund_payment, schedule_appointment.

• The verb comes first. Never noun-first (customer_get), never camelCase

(getCustomer), never PascalCase (GetCustomer), never a bare noun (customer).

2. Identifier parameters

• Every identifier parameter is named <entity>_id: customer_id, order_id,

invoice_id, user_id, ticket_id, payment_id.

• Never a bare id, never identifier, never customerId (camelCase), never pk.

3. Docstring sections, in this exact order

The docstring has exactly these five parts, always in this order:

1. One imperative line stating what the tool does ("Retrieve a customer

record by ID."). Never "Helps with…", never "Can be used for…", never a noun phrase ("Customer retrieval.").

1. Use when: — a section literally headed Use when: with 2–4 bullet

trigger conditions (when an agent should reach for this tool).

1. Args: — every parameter listed with its type AND a concrete format

example (not just "the customer id" — Format "CUST-######", e.g. "CUST-000042").

1. Returns: — a description of the output shape.
2. Errors: — the named error codes (see rule 5).

4. Read tools take a format parameter

• Every read/retrieve/get/lookup/fetch tool takes format: str = "concise".
• The only two accepted values are "concise" and "detailed". The default is

"concise". Never invent a third value ("summary", "full", "verbose"), never default to "detailed", never use a bool like verbose=False.

5. Error codes

• Each error is a named UPPERCASE_SNAKE code drawn from this vocabulary:

NOT_FOUND, INVALID_FORMAT, MISSING_FIELD, UNAUTHORIZED.

• Each error line states what the agent should change before retrying.
• An error message must include the offending value AND a concrete example of a

valid value. Never just "failed", "error", or "invalid input".

6. MCP tool references

• When prose (a system prompt, an instruction) tells an agent to call an MCP

tool, write the fully qualified ServerName:tool_name with a colon: BigQuery:bigquery_schema, GitHub:create_issue.

• Never the bare bigquery_schema. Never a dot (BigQuery.bigquery_schema),

never a slash (BigQuery/bigquery_schema).

Worked examples (BEFORE → AFTER)

Rule 1 — naming

BEFORE (base default — noun-first or camelCase):

python
def customerGet(id): ...
def customer_lookup(id): ...

AFTER (house style):

python
def get_customer(customer_id: str, format: str = "concise"): ...

Rule 2 — identifier parameter

BEFORE:

python
def get_order(id: str): ...
def get_order(identifier: str): ...

AFTER:

python
def get_order(order_id: str, format: str = "concise"): ...

Rule 3 — docstring shape

BEFORE (free-form prose, no fixed sections):

python
def get_invoice(invoice_id):
    """Look up an invoice. Pass the invoice id and it returns the invoice."""

AFTER:

python
def get_invoice(invoice_id: str, format: str = "concise"):
    """
    Retrieve an invoice by ID.

    Use when:
    - The user asks about a specific invoice's amount or status.
    - Invoice context is needed before issuing a refund.

    Args:
        invoice_id: Format "INV-######", e.g. "INV-000042".
        format: "concise" (key fields) or "detailed" (full record). Default "concise".

    Returns:
        Invoice object with the requested fields.

    Errors:
        NOT_FOUND: No invoice with that id; verify the id and retry.
        INVALID_FORMAT: id must match INV-######, e.g. "INV-000042".
    """

Rule 4 — format parameter

BEFORE:

python
def get_account(account_id, verbose=False): ...
def get_account(account_id, mode="full"): ...

AFTER:

python
def get_account(account_id: str, format: str = "concise"): ...

Rule 5 — error codes

BEFORE (prose, no recovery signal):

python
return {"error": "Customer lookup failed."}

AFTER:

python
return {
    "code": "INVALID_FORMAT",
    "message": "order_id '12345' is not valid; expected CUST-######, e.g. 'CUST-000042'. "
               "Reformat the id and retry.",
}

Rule 6 — MCP reference

BEFORE:

text
Use the bigquery_schema tool to fetch table schemas.

AFTER:

text
Use the BigQuery:bigquery_schema tool to fetch table schemas.

Edge cases & exceptions

• Write/action tools still take no format param. Rule 4 is for reads only.

create_order, cancel_subscription, refund_payment do NOT get a format parameter — only get/retrieve/lookup/fetch tools do.

• Multi-word entities keep the <entity>_id shape: a calendar event's id is

event_id (or calendar_event_id), a support ticket's is ticket_id. The verb may have a noun suffix too (update_customer_email) — still verb-first snake_case.

• A tool with no identifier (e.g. send_notification keyed on a recipient)

still names that recipient user_id, not to or recipient.

• A non-standard error that isn't in the four-code vocabulary: still emit an

UPPERCASE_SNAKE code (e.g. RATE_LIMITED), with the same recovery + example rule.

• Use when: with a single trigger is too thin — give 2–4 bullets. If the tool

truly has one trigger, it is probably over-narrow; consolidate, but still write ≥2.

Do / Don't

• DO name tools verb_noun. DON'T put the noun first or use camelCase.
• DO name id params <entity>_id. DON'T use bare id or identifier.
• DO write a literal Use when: heading. DON'T fold triggers into the first line.
• DO give a concrete format example for every Args parameter. DON'T write

"the customer id" with no example.

• DO add format: str = "concise" to read tools. DON'T use verbose=, mode=,

or default to "detailed".

• DO use UPPERCASE_SNAKE error codes with a fix + valid example. DON'T return

"failed" or "invalid input".

• DO qualify MCP tools as ServerName:tool_name. DON'T reference the bare tool name.

Common mistakes (the base's wrong defaults)

1. Names the tool after the noun (customer_lookup, CustomerGet) instead of

verb-first get_customer.

1. Uses a bare id parameter instead of customer_id.
2. Writes a free-form docstring with no Use when: heading and no fixed section

order.

1. Omits the format parameter on read tools, or invents verbose/mode/a third

value.

1. Describes errors in prose ("if it fails, the customer wasn't found") instead of

UPPERCASE_SNAKE named codes with a valid-value example.

1. References an MCP tool by bare name (bigquery_schema) with no ServerName:

prefix.

Quick checklist

• ] Name is verb_noun snake_case.
• ] Id param is <entity>_id, never bare id.
• ] Docstring order: imperative line → Use when: → Args: → Returns: → Errors:.
• ] Read tool has format: str = "concise" (only concise/detailed).
• ] Errors are UPPERCASE_SNAKE with a fix + concrete valid example.
• ] MCP refs are ServerName:tool_name with a colon.