PermitStack

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds substantive context beyond them: the 25-per-page cap and, notably, the fields deliberately absent from results (no owner name, owner mailing address, or applicant name), which prevents an agent from promising data it cannot get here.

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 dense sentences: purpose and identifier source first, then return shape, then the explicit field exclusions. There is no filler, and the most important constraints are front-loaded.

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 takes on the burden of describing return contents (work history fields: dates, categories, values) and their gaps, plus page sizing. The only remaining soft spot is the page-vs-start interaction, which the schema covers but the description does not reinforce.

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 page, start, per_page limits, and that contractor_id comes from search_contractors results. The description's mention of the UUID source and the 25-per-page ceiling largely restates that, adding little new semantics. Baseline 3 applies when the schema carries the parameter burden.

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 the permits pulled by one contractor') with an explicit scope restriction to a single contractor rather than all permits. It names search_contractors as the source of the required identifier, which helps distinguish it from that sibling. However, it never explicitly contrasts itself with search_permits, the closest alternative for permit queries.

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 gives clear entry conditions: you must already have a contractor UUID obtained from search_contractors, which establishes the tool chain an agent needs. It stops short of naming a when-not case or pointing to search_permits for property- or address-based queries, so the routing guidance is good but not complete.

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?

Adds substantial context beyond annotations: the output changes with auth state (full jurisdiction listing signed-in vs. totals only otherwise), results are capped at 25 and ordered largest-first, and `data_through` semantics are defined. Annotations already cover safety (readOnly/idempotent/non-destructive), and the description layers on the conditional and pagination behavior an agent needs.

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 sentences that front-load purpose, then conditional behavior, then the fallback case. The `data_through` parenthetical is well-placed and no sentence is wasted; density serves clarity rather than obscuring it.

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 does the heavy lifting by describing returned fields, filtering, and pagination ordering. The only soft gap is that 'up to 25 per call' implies paging but there is no offset/cursor param, so how an agent retrieves jurisdictions beyond the first 25 is left unaddressed.

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 both params (name, state) are fully documented, so the baseline is a 3. The description's 'filterable by state and by name' mostly restates the schema, adding only the useful nuance that filtering applies to the signed-in jurisdiction listing.

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?

A specific verb ('Describe') plus a clearly bounded resource ('PermitStack's coverage') enumerating what is returned: total permits, jurisdictions by status, and states. The purpose is unambiguous, though it never names a sibling to distinguish itself from search_permits or search_contractors — an agent infers the 'metadata vs. records' split on its own.

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?

It explains the signed-in vs. anonymous behavior, which implies this is a discovery/orientation call, but it never states when to reach for it over search_permits or search_contractors. No explicit when-to-use or exclusion guidance is given; the routing is left 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?

Beyond the annotations, the description discloses important behavior: case-insensitive exact matching, up to 5 results because numbers can repeat across jurisdictions, a partial-match fallback signaled by the `match` field, date-window limiting through `account_window_from`, and missing owner/applicant fields in results. This is substantial behavioral context not present in the annotations.

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 front-loaded with the core purpose and then adds tightly relevant details about matching, result limits, fallback behavior, date windows, and omitted fields. It is dense but every clause earns its place and there is no filler.

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 still explains the result shape sufficiently: up to 5 permits, a `match` field for partial results, `account_window_from` behavior, and which fields are absent. An agent has enough information to invoke and interpret this lookup tool 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%, so the schema already documents all three parameters. The description still adds meaning by explaining that city/state disambiguate duplicate numbers and that permit_number is matched exactly while ignoring case, plus the fallback behavior tied to location parameters.

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: looking up a permit by the jurisdiction-assigned permit number, optionally narrowed by city and state. It clearly implies an exact-number lookup rather than a broad search, but it does not explicitly name or differentiate itself from the sibling search_permits tool.

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?

It explains when to add city or state to disambiguate duplicate permit numbers across jurisdictions, and it describes the partial-match fallback when no exact match exists. It does not explicitly say when to use this tool versus search_permits or other sibling tools, so it provides clear context but no exclusions or alternative routing.

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?

Beyond the annotations, the description discloses pagination behavior (up to 25 records per page, newest first), the meaning of `has_more`, the limited-account date-range caveat with `account_window_from` and `_notes`, and the absence of owner/applicant fields. This adds substantial behavioral context that an agent would not get from the annotations alone.

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 definition is front-loaded with the core lookup purpose, then layers on matching rules, return shape, pagination, and caveats. Every sentence carries useful information, though the density and length make it slightly heavier than ideal.

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 carries the burden of explaining returns, and it does: property profile contents, permit timeline, category breakdown, contractors, pagination, and limited-account caveats. That is complete enough for an agent to call and interpret the tool 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 description coverage is 100%, so the schema already documents all parameters, including address format, optional city/state/ZIP, page, start, and per_page. The description reinforces address matching and duplicate-address narrowing, but it does not add syntax or constraints beyond the schema, so baseline 3 is appropriate.

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: permit history for one property, looked up by street address. It clearly distinguishes a single-property lookup from broader search tools through the phrase 'one property' and by noting it covers all permit categories. It does not explicitly name sibling alternatives, which keeps it from 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?

It gives useful contextual guidance: optional city, state, and ZIP narrow ambiguous addresses, and limited-account date ranges affect result completeness. However, it does not say when to use this instead of get_permit or search_permits, so usage is only implied rather than routed explicitly.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial context on top: a hard 25-result cap per call, sort order by activity score descending, the exact field set returned, and the explicit exclusion of project values. With no output schema, this is the kind of disclosure that would otherwise be missing.

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 sentences, front-loaded with the filterable dimensions, then the return contract, then the sibling hand-off. The return-field enumeration is dense but earns its place given there is no output schema; the only mild redundancy is repeating the 25-per-call cap twice.

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 an eight-parameter, zero-required search tool with no output schema, the description covers result fields, ordering, page cap, and the sibling escape hatch for values. It leaves open how multiple filters combine and what an unfiltered call returns, which an agent may need to reason about.

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 all eight parameters are already documented, including the page-vs-start pagination interplay and the per_page maximum. The description only restates the filter dimensions named in the schema (name, city, state, specialty) and adds no meaning about combinations, matching behavior, or defaults, 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?

Names a specific verb and resource (search contractors) plus the exact filter dimensions (name, city, state, specialty), and explicitly contrasts itself with get_contractor_permits for the data it does not return. An agent can tell what this tool yields and what it does not without opening the 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?

Explicitly routes the agent to get_contractor_permits when project values are needed, which is a real selection criterion among the siblings. It gives no guidance on when to prefer this over search_permits or get_property_history, and does not state what to do when all filters are omitted.

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?

Beyond the annotations, which already establish read-only, idempotent, non-destructive behavior, the description adds substantial operational detail: the 25-result cap, total/total_capped/total_unknown semantics, account date-window clamping, HVAC/MECHANICAL category aliasing, issue-date-else-filing-date behavior, and the explicit absence of owner/applicant fields.

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 dense but appropriately sized for a 23-parameter search tool with no output schema. It is front-loaded with the searchable dimensions, then moves directly into return behavior and important edge cases, and each sentence contributes either scope, response semantics, or a caveat an agent needs.

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?

Given the complexity, the high schema coverage, the annotations, and the absence of an output schema, the description is complete enough to call the tool safely. It explains return counts, result fields, coverage-window behavior, category aliasing, date ambiguity, and missing privacy-sensitive fields; the only notable omission is sibling routing guidance, which is captured under usage guidelines.

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 the schema already carries the main parameter documentation. The description still adds useful semantic quirks not fully captured there, especially category HVAC/MECHANICAL mutual matching, date_after/date_before falling back to whichever date is published, and the account-window limitation.

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 a specific verb and resource: search U.S. building permits, with a well-defined filter scope covering location, category, status, dates, value, contractor, and free text. It is distinguishable from a single-permit lookup, but it does not explicitly name or contrast with siblings such as get_permit or get_contractor_permits.

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 search-oriented purpose and filter list, so an agent can infer this is the tool for filtered permit searches. However, the description gives no explicit when-to-use guidance, no exclusions, and no comparison to siblings like get_permit, get_contractor_permits, or get_property_history.

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