get_custom_fields

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

With no annotations, the description carries the burden and does well: it enumerates the returned fields, warns that DataMart keys are case- and accent-sensitive and may carry trailing spaces, and explains multilingual keying per languageId. It omits permissions/pagination/refresh behavior, but for a read-only definition lookup this is substantial context.

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?

Front-loads the purpose, then return shape, then the non-obvious DataMart key semantics, then sibling routing — a sensible information order. Slight redundancy in re-listing the eight entity types already encoded in the enum, and the trailing-spaces warning is dense but earns its place.

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?

There is no output schema, so the description compensates by listing the returned fields (Id, BaseId, Name, TypeId, TypeName, Description, Required). Combined with the DataMart key guidance and the sibling pointer, an agent has enough to call it and use the result correctly; only auth/pagination behavior is unstated.

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%, so baseline is 3, but the description adds real meaning for languageId: on multilingual accounts key names follow each component's language and definitions must be fetched per languageId to map variants of the same BaseId. The entity list merely restates the enum and adds no new meaning.

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?

States a specific verb (get) and resource (custom field definitions) plus the exact entity scope covered. It also distinguishes itself from the closely named sibling get_custom_field_options, so an agent can route without opening both 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?

Gives concrete downstream routing: query values via query_datamart with examples of the filter shape, and use get_custom_field_options for dropdown values. It lacks an explicit negative case (e.g. versus get_reference_data), but the positive guidance is unusually actionable.

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