Create a ServiceNow UI Builder page and register its URL route, specifying parent app, path, title, and layout.
Create a new UI Builder page with route registration. [Write]
| Name | Required | Description | Default |
|---|---|---|---|
| app | No | Parent UX app sys_id | |
| path | Yes | URL path segment | |
| title | Yes | Page title | |
| layout | No | Layout type: single, sidebar, tabbed (default single) |
Changes observed during successful MCP inspections.
v1.0.2Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description includes '[Write]' to indicate it is a write operation, which aligns with the readOnlyHint=false annotation, and adds the side effect of route registration. However, it does not disclose permissions, error conditions, or reversibility. Beyond the annotation, only the route registration is new context, so it is adequate but not rich.
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, front-loaded sentence with no filler. 'Create a new UI Builder page with route registration' efficiently conveys the core action, and '[Write]' adds a useful side-effect hint without unnecessary length.
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 create operation with a well-documented schema, the description covers the core purpose adequately. However, with no output schema, it does not describe the return value, and it omits any mention of required permissions or how route registration interacts with the optional 'app' parameter. It is sufficient but has room for more detail.
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 of all four parameters with descriptions, so the description does not add any additional parameter semantics. It does not explain defaults, relationships, or how parameters like 'app' and 'layout' affect the result beyond what the schema already states.
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 action ('Create') and the resource ('UI Builder page'), and adds 'with route registration' which distinguishes it from update/delete/list page tools and from component or route-only creation tools. It is specific and unambiguous.
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?
No guidance is provided on when to use this tool versus alternatives like list_uib_pages or update_uib_page. There is no mention of prerequisites (e.g., needing an existing UX app) or when not to use this tool. The description only states what it does, not when to choose it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.