UteamUP CMMS

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds meaningful behavior beyond that: the specific content returned (attributes, breadcrumb, documents, tags, linked records), the not-found error on unknown GUIDs, and the required Asset.View permission.

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?

Four tight sentences with zero filler, front-loaded with purpose and then layering returns, error behavior, and permissions. Every sentence carries distinct information.

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 no output schema, the description responsibly enumerates the returned payload and documents the failure mode and permission requirement. It is nearly complete; only the sourcing of a valid GUID (i.e., routing to search/list) is left implicit.

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% and the single guid parameter is fully documented in the schema as an ExternalGuid UUID. The description echoes 'stable public GUID' but adds no format or sourcing detail beyond the schema; baseline 3 applies.

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 states a specific verb and resource ('Retrieves an asset's details') and the lookup key ('by its stable public GUID'), which distinguishes it from list/search siblings without naming them. It is clear but does not explicitly contrast with uteamup_asset_search, so it falls short of a 5.

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: you need a GUID to call it, and the alternatives (list/search) would be the routing path when you don't have one, but the description never states this. No when/when-not guidance or named alternatives are provided.

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

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

Annotations already declare the operation safe (readOnlyHint=true, destructiveHint=false, idempotentHint=true). The description adds value beyond them by enumerating the returned fields and stating the required permission, which is exactly the kind of context annotations do not cover. It does not address rate limits or pagination limits, but with no output schema the field list is a meaningful addition.

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?

Three tight sentences: purpose first, then return payload, then prerequisite. Every sentence earns its place and nothing is repeated from the schema or annotations.

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 two-parameter list tool with no output schema, the description covers purpose, pagination, returned fields, and permission requirements well. The remaining gap is the absence of any comparison to the asset_search sibling, which would matter for correct tool selection.

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 100% for both parameters, so the schema fully documents page and pageSize (including defaults and max). The description only implies pagination generally and adds no syntax or format details beyond the schema, so the baseline 3 is correct.

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 (Lists) and resource (assets) with scope (authorized company) and pagination, which is clear. However, it never distinguishes itself from the sibling uteamup_asset_search or uteamup_asset_get_by_guid, so an agent must infer the difference from names alone.

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 explicit when-to-use or when-not-to-use guidance, and no named alternatives. The permission prerequisite ('Requires Asset.View permission') is a useful implied condition for use, but the description never routes the agent between this and the asset_search sibling.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond them by stating the Asset.View permission requirement, the tenant scope ('authorized company'), and what comes back ('asset details and public GUIDs') — meaningful because no output schema exists. It omits any note on result caps or paging for a potentially broad match.

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?

Three short sentences, front-loaded with the verb and scope, then the return payload, then the permission prerequisite. No filler or redundancy; every clause carries information.

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 one-parameter read tool with no output schema, the description supplies the return content, the permission gate, and the scope constraint. The only missing piece is behavior for large result sets (pagination or truncation), which matters for a substring search.

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 100%, and the schema already documents the length limit, case-insensitivity, and the anti-parameter hint about searchTerm. The description only restates the match target, so the baseline 3 is appropriate — the schema does the heavy lifting.

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 (searches) and resource (assets) with a clear matching criterion (partial name or serial number) scoped to the authorized company. It is distinguishable from uteamup_asset_list and uteamup_asset_get_by_guid by that matching criterion, though it never names the siblings explicitly.

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 by the matching rule: use this when you have a partial name or serial number rather than a GUID or a need to enumerate everything. However, no alternative is named and no exclusion is stated (e.g. 'use uteamup_asset_list to browse all assets'), so the agent must infer routing from the sibling names.

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

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

Annotations already declare readOnly, idempotent, non-destructive, non-open-world behavior, so the safety profile is covered. The description adds genuinely useful context beyond that: the required permissions (WorkOrder.View vs WorkOrder.View.Own), the fact that own-access silently narrows results to the actor, and the status semantics distinguishing Completed, Cancelled, and Unknown.

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-loaded with the core purpose, then filters, then return shape, then status semantics and permissions. Four dense sentences with little waste, though the status-semantics sentence is arguably detail an agent only needs at interpretation time.

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, and the description compensates by enumerating the returned fields (public GUID, name, description, numeric status, statusName, assigned user). Combined with permission and status caveats, an agent has enough to call and interpret the tool; only pagination metadata/total-count behavior is left 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 description coverage is 100%, so every parameter is already documented, including defaults and the pageSize max. The prose restates asset GUID, text search, and open-only filtering without adding format or behavior detail beyond the schema, so the baseline 3 applies.

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 gives a specific verb and resource ('Lists work orders in the authorized company') and names the supported filters precisely. It is clear about scope, but it never mentions the sibling uteamup_workorder_search, so an agent must infer which of the two listing/search tools fits a given query.

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 context is implied through the filter descriptions (asset GUID, text search, open-only) and the permission note, which suggests when a caller gets a narrower result set. However, there is no explicit when-to-use guidance and no routing to the alternative uteamup_workorder_search, leaving the choice to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: the required permission scopes, the fact that own-scope access silently narrows results to the actor's work orders, and the meaning of the status values returned. It does not mention result limits or pagination, which keeps it from a 5.

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-loaded with the core action and scope, then permissions and status semantics. The status-value explanation (Completed/Cancelled/Unknown) is slightly tangential to a search tool but earns its place by clarifying returned data in the absence of an output schema.

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 no output schema, the description compensates by naming the returned fields (public GUIDs, numeric status, statusName) and explaining status values. Permissions and scope behavior are covered. Missing only result-size or ordering behavior, which an agent would want for a search tool.

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% and the single parameter already documents partial, case-insensitive matching against title and description. The description restates the same semantics ('partial search term', 'titles and descriptions') without adding format, length, or escaping guidance, so the baseline 3 applies.

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 and resource ('Searches work-order titles and descriptions') plus scope ('in the authorized company using a partial search term'), which is enough to distinguish it from a plain list operation. It does not explicitly name the sibling uteamup_workorder_list as the non-search alternative, so it stops short of a 5.

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 useful context on permissions (WorkOrder.View vs WorkOrder.View.Own) and the consequence of own-scope access, which helps an agent predict results. However, it never states when to prefer this over uteamup_workorder_list or what to do when the search term is too broad, so usage guidance is implied rather than explicit.

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