diff --git a/types/lib/mixins/element-mixin.d.ts b/types/lib/mixins/element-mixin.d.ts
index afcb31e67a..6658ed4ad3 100644
--- a/types/lib/mixins/element-mixin.d.ts
+++ b/types/lib/mixins/element-mixin.d.ts
@@ -209,6 +209,10 @@ declare namespace Polymer {
      * this element. This method will return the same URL before and after
      * bundling.
      *
+     * Note that this function performs no resolution for URLs that start
+     * with `/` (absolute URLs) or `#` (hash identifiers).  For general purpose
+     * URL resolution, use `window.URL`.
+     *
      * @param url URL to resolve.
      * @param base Optional base URL to resolve against, defaults
      * to the element's `importPath`
diff --git a/types/lib/utils/resolve-url.d.ts b/types/lib/utils/resolve-url.d.ts
index 6d894f64c6..5aae176fff 100644
--- a/types/lib/utils/resolve-url.d.ts
+++ b/types/lib/utils/resolve-url.d.ts
@@ -21,6 +21,10 @@ declare namespace Polymer {
     /**
      * Resolves the given URL against the provided `baseUri'.
      *
+     * Note that this function performs no resolution for URLs that start
+     * with `/` (absolute URLs) or `#` (hash identifiers).  For general purpose
+     * URL resolution, use `window.URL`.
+     *
      * @returns resolved URL
      */
     function resolveUrl(url: string, baseURI?: string|null): string;