Umarelli

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds useful data-coverage context (which record sections are returned), but says nothing about failure behavior for malformed ids, missing buildings, or latency — relevant for a tool that accepts three id formats.

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?

Two sentences, front-loaded with the purpose and followed immediately by the accepted id formats. No filler or repetition of the title.

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 single-parameter read tool with no output schema, the description covers purpose, id formats, and record contents well. The only gap is error/empty handling for unknown or malformed ids, which an agent would benefit from knowing before calling.

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 the baseline is 3; the description earns a bump by specifying concrete id syntax (ten-digit NYC BBL, jc:14106:39 form, Umarelli URL) that the schema only gestures at generically. It still doesn't say how invalid ids are handled.

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 ('Get one building's record from Umarelli') and enumerates exactly what the record contains (permits, assessed value, tax bill, tax breaks, zoning, news). Singular 'one building' implicitly contrasts with the sibling 'search', but no sibling is named explicitly, so the differentiation is left to inference.

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 only implied: the description clarifies that ids come as a BBL, a jc: id, or a URL, which hints at the search-then-fetch workflow, but it never says when to use this instead of 'search' or 'recent_permits'. No prerequisites, error conditions, or exclusions are stated.

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 readOnlyHint and openWorldHint, and the description adds real value beyond them: sort order ('newest first'), the differing date basis per city (filing vs issue), and that each result includes an Umarelli link. It also implicitly scopes results to new-building and major-renovation permits only, a useful filtering disclosure.

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?

A single front-loaded sentence with zero filler; the resource, geography, ordering, and output shape are all packed in without redundancy.

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 correctly sketches the return shape (permit with Umarelli link) and ordering, but leaves the two optional parameters' meaning and effect unexplained. For a three-param tool with low schema coverage that is an incomplete picture.

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 only 33% — `limit` and `radius_meters` have no descriptions, only bounds and defaults. The description mentions 'near' but never explains the radius parameter, its units, default, or the limit/pagination behavior, so it fails to compensate for the coverage gap.

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 ('List new-building and major-renovation permits'), plus the geography (NYC/Jersey City) and the scoping qualifier ('near a street address'). An agent can distinguish this from the generic `fetch` and `search` siblings without opening any schema.

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?

The description implies when the tool applies (looking up recent permits around an address) but offers no explicit when-not conditions or routing against the `fetch`/`search` siblings. Usage must be inferred from the purpose statement alone.

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 readOnlyHint=true and openWorldHint=true, matching the description's read-only external lookup. The description adds genuinely new behavioral context: the exact return shape (ids, names, Umarelli URLs) and a non-obvious default that New York City is assumed unless "Jersey City" is included in the query.

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 and geography first, return values and the fetch handoff second, the location default last. No filler and nothing redundant with structured fields.

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, but the description compensates by naming what is returned (ids, names, page URLs). Combined with the annotations and full schema coverage, an agent has everything needed to call this correctly.

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 schema supplies an address example, so the baseline is 3. The description exceeds that by documenting the location-defaulting behavior — an agent must know to embed "Jersey City" in the query string to search there, which the schema alone does not convey.

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 ("Find buildings") and scopes it geographically to New York City or Jersey City by street address. It explicitly contrasts with the sibling fetch by explaining that this returns ids to pass onward, so an agent can tell the two apart without inspecting 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 clear when-to-use context (address lookup) and an explicit alternative: "pass an id to fetch for the full record." It does not address the other sibling, recent_permits, but the routing to fetch is unambiguous.

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