mcp

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description adds meaningful operational context beyond annotations: API-key authentication, a 50-requests-per-day quota shared with data.ungovr.org, and where to get a key. It stops short of describing throttling or error behavior, but this is strong disclosure for a read-only endpoint.

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 compact sentences: purpose and return contents first, then authentication and rate-limit constraints. Every sentence earns its place, including the key-acquisition URL.

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?

No output schema exists, so the description appropriately states what the response contains (findings, recommendations, responses). It also covers the key prerequisites an agent needs before invoking the tool: authentication and daily quota. Nothing essential for correct invocation is missing.

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?

There is only one parameter and schema description coverage is 100%, so the schema already explains that 'id' is a report ID from search results. The description reinforces that the lookup is by ID but adds no syntax, format, or validation detail beyond what the schema provides. 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 ('Get full details for a specific California Grand Jury report by ID') and lists what the result includes. It is clearly distinct from the sibling search_cgj_reports, which searches rather than retrieves a single report.

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 usage context: the caller must supply a report ID from search results and an X-API-Key, with a URL to obtain one. It does not explicitly say when not to use it or name search_cgj_reports as the required first step, but the intended workflow is strongly implied.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond that by enumerating the returned fields (name, type, website, parent, children, domain status, metadata) and confirming depth-independent behavior. Missing only failure behavior for an invalid slug.

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, no filler. The core action and the key identifier come first, supporting examples follow. 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?

With a single required parameter and no output schema, the description covers the essentials by listing return fields and the breadth of the hierarchy. It falls short only on edge cases (invalid/unknown slug behavior) and on routing guidance against sibling lookup tools.

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 slug parameter's own description already gives examples and says 'at any depth'. The description reinforces the depth flexibility and adds a deeper nesting example, but adds no syntax rules beyond the schema. Baseline 3 applies when 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+resource ('Get full details for a specific government entity') keyed on a URL slug, and names the entity types covered (cities, school districts, special districts). It is clearly distinguishable from sibling search/list tools like search_entities and list_countries.

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 rather than stated: the tool requires an exact URL slug, and the description shows two example slugs, which hints that you need the identifier already. However, it never explicitly says when to use this versus search_entities or resolve_jurisdiction when you only have a name or domain.

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 (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description's value-add is the resolution behavior: a child-slug query falls back to a parent jurisdiction and signals that via 'resolved_from'. That is non-obvious behavior an agent could not infer from structured fields. It stops short of saying what happens on an unresolvable slug (error vs empty result).

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?

Every sentence carries information: the returned fields, the accepted slug forms, the US-federal special case, and the resolved_from marker. It is dense but front-loaded and free of filler; the field enumeration in sentence one is long but justified since there is no 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 correctly compensates by listing the returned data and the one non-obvious response field (resolved_from). Input handling is also fully covered. The only gap is failure behavior for invalid or ambiguous slugs, which matters for a single required parameter but is a modest omission.

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 would be 3, but the description goes further than the schema: it explains the full slug grammar (country, country/state, deep entity slugs) and the parent-resolution semantics, which the schema's brief examples do not convey. The added meaning is genuine rather than restated.

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 opens with a specific verb and resource ('Get the open records law ... governing a jurisdiction') and immediately enumerates what the payload contains (citation, deadlines, fees, exemptions, appeals, retention, rating). That scope clearly separates it from siblings like search_transparency_laws (which searches) and resolve_jurisdiction (which resolves slugs), so an agent can pick it 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?

It gives a clear picture of when the tool applies — any entity slug at any depth resolves to the governing law, and US federal FOIA is 'us' — which is real usage context. What it lacks is any exclusion or explicit routing to alternatives, e.g. telling the agent to use resolve_jurisdiction or search_transparency_laws first when it doesn't know a slug.

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, openWorldHint=false, and destructiveHint=false. The description adds meaningful context beyond annotations by stating the tool is public and requires no API key, and by clarifying that it returns a full hierarchy/coverage footprint. It does not describe pagination, rate limits, or response structure, so it is not 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?

The description is two tight sentences, front-loaded with the tool's purpose and followed by parameter meanings and access conditions. Every sentence adds value and there is no wasted text.

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-only lookup with no output schema, the description covers the product meanings and access conditions adequately. It is slightly incomplete in that it says "full hierarchy" without describing the response shape, pagination, or hierarchy structure, so a 4 is appropriate.

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 adds useful meaning beyond the enum labels by explaining that "request" returns the worldwide Request coverage footprint and "cgj" returns Civil Grand Jury coverage. That helps an agent choose the correct enum value.

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: "Get the full hierarchy of government entities where an UnGovr product is available." It clearly states what the tool returns. It does not explicitly differentiate itself from siblings like list_countries or resolve_jurisdiction, so it falls short of a 5 under the rubric.

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 product values: use it to get the Request or CGJ coverage footprint. The description does not state when to use this tool versus alternatives such as list_countries or resolve_jurisdiction, and it gives no exclusions or prerequisites beyond "Public, no API key required."

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-redundant behavior: results are filtered to countries that actually have entity data, and each entry carries entity counts and coverage metadata. It stops short of saying whether the list is complete, paginated, or ordered.

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?

One sentence that front-loads the verb and resource, then layers the scope constraint and the returned fields. Nothing is redundant and nothing needs trimming.

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 in play, the description carries the burden of describing returns, and it does so at a high level (entity counts, coverage metadata). For a zero-param enumeration tool that is nearly sufficient; a note on whether all countries or only covered ones are returned, and in what shape, would close the gap.

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 tool takes no parameters, which is the baseline-4 case. The description is consistent with a parameterless call and implies it returns the full country set rather than requiring filters.

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?

Specific verb plus resource ("List all countries") with a clear scope qualifier: only countries that have government entity data in UnGovr. The clause about entity counts and coverage metadata further pins down what a result row contains. It doesn't explicitly contrast with the nearest sibling (get_product_coverage), but the purpose is unmistakable.

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: an agent can infer this is the discovery/enumeration step before calling search_entities or resolve_jurisdiction, but the description never says so and names no alternative. No prerequisites or exclusion conditions are stated, though for a zero-parameter reference list there is little to exclude.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds useful behavior beyond that: results are grouped by category, and coverage is limited to US, IE, and GB. It does not discuss pagination or result size, which is a minor gap for a reference-data lister.

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 what the tool returns, followed by the routing hint and the supported-country constraint. Every sentence carries distinct information with no repetition.

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 one optional parameter, no output schema, and strong annotation coverage, the description supplies everything an agent needs: purpose, return structure, downstream consumer, and country coverage. Nothing material is missing.

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 optional parameter is fully documented, including the default "us". The description restates the country scope and spells out two of the codes (Ireland, United Kingdom), adding only marginal meaning 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?

States a specific verb (List) and resource (service request categories and types) scoped to a country, and adds the return shape (grouped by category). It is clearly distinguishable from siblings like submit_service_request, which consumes its output.

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?

"Use this to discover valid service_type_id values for submit_service_request" gives an explicit downstream purpose and routes the agent to the consuming tool. It also lists supported countries, though it does not state any exclusion or prerequisite (e.g., what happens for unsupported countries).

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, it discloses the data method (entity_domains), fallback inference behavior, the possibility of 'unknown', and explicit exclusions for server/edge-node location and IP addresses. It also documents authentication requirements and a 50 req/day shared rate limit, which are important operational constraints.

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 mapping behavior, then adds method, fallback, exclusions, and auth details in a logical order. It is dense but every sentence contributes useful selection or invocation context.

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-only resolver with no output schema, the description covers method, fallbacks, exclusions, auth, and rate limits well. It could be slightly more complete by specifying the returned jurisdiction format or confidence semantics, but the essential invocation context is present.

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 input schema already documents that the parameter accepts a hostname or URL and rejects IP addresses. The description reinforces the IP rejection and adds legal-operator context, but it does not add parameter syntax or format details beyond the schema.

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: mapping a domain to the jurisdiction governing its operator. It clearly distinguishes legal operator jurisdiction from server or edge-node geography. However, it does not differentiate this tool from the sibling resolve_jurisdiction, so an agent cannot tell from the description alone which resolver to choose.

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 clear usage context: authoritative for government domains in the UnGovr corpus, otherwise suffix/ccTLD inference, and IP addresses are refused. The main gap is that it does not name the sibling alternative or explain when to use resolve_jurisdiction instead.

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?

Goes well beyond the readOnly/openWorld annotations: discloses the upstream data source and license, that results carry a crosswalk version, that failures return a reason rather than a guess, that IPs are refused and not echoed back, and that calls are free but rate-limited per IP. That is exactly the operational context annotations cannot carry.

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-loads the core mapping and the accepted inputs before the exclusion list, with no filler sentences. Slightly dense and includes publisher/license provenance that an agent rarely needs, but it is still a compact two-sentence block.

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?

No output schema exists, so the description enumerates the return payload itself: canonical URN, governing-layer stack, OCD-ID, Wikidata QID, precision, failure reason, and crosswalk version. Combined with the refusal semantics, nothing an agent needs to call this correctly is missing.

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 baseline is 3. The description adds real meaning beyond the schema by explaining the two-argument edge pattern (country 'US' plus region 'CA') and the three accepted code forms, clarifying how the two parameters interact rather than just restating them.

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 (maps) and resource (ISO 3166 code → UnGovr jurisdiction), and explicitly scopes itself against the similar-sounding resolve_domain_jurisdiction by listing what it will not resolve (IP addresses, cities, postal codes). An agent can pick between this and list_countries without opening either 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?

Gives clear usage context: accept-country, subdivision, or country+region pairs, and explicit exclusions (IPs refused, city/postal unsupported, XX/T1 return a reason). It stops short of naming sibling tools as alternatives, so the routing guidance is present but not fully explicit.

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 establish a read-only, non-destructive profile, and the description goes well beyond them: it discloses the X-API-Key header requirement, a concrete rate limit (50 req/day), and where to obtain a key. It also states the return payload shape (title, year, county, themes), which annotations cannot convey.

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 compact sentences that front-load purpose and return shape, then auth/rate limit, then the county-value prerequisite. Every sentence carries actionable information; no filler or restatement of the name.

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 no-output-schema, fully-documented-parameter search tool, the definition covers what is returned, how to authenticate, the quota ceiling, and how to resolve the one free-text field with no enum constraint. Nothing an agent needs in order to call it correctly is missing.

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, and the description adds real meaning on top: it confirms all filters are optional/combinable and points to the UnGovr entity API as the source of valid county names, compensating for the absence of enums on county. It does not address limit/offset semantics, hence not a 5.

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 (search) plus the resource (California Grand Jury reports) and enumerates the filter dimensions (county, year, title keyword), then names what the response contains. The 'search' vs 'get' contrast with the sibling get_cgj_report makes the scope distinction obvious without opening either 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?

Gives clear usage context: the three filter dimensions, that they combine with 'and/or', and a prerequisite pointer for obtaining valid county values. It does not explicitly route the agent away from get_cgj_report or state when no filters should be used, so it stops short of full when/when-not guidance.

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, non-destructive, non-open-world), and the description adds real value beyond them: the composition of the result (slugs, types, website URLs), the meaning of the "scope" output field, and the strict-input contract ("Unrecognized arguments are rejected, not ignored"). Pagination behavior and default/max limits are left to the schema.

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 purpose, then coverage, then return shape, then the scope caveat, then validation. Each sentence earns its place, though the tier enumeration and the type enumeration partially overlap in content.

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?

No output schema exists, and the description compensates by describing the returned fields and the semantics of the "scope" discriminator, which is the main place an agent could misread results. Combined with a fully documented six-parameter schema, nothing essential to correct invocation is missing.

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%, including the explicit note that the parameter is named "type" not "entity_type", so the schema already carries the semantics. The description only restates the parameters at a high level without adding format, precedence, or interaction details (e.g., how query and type combine), so 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+resource ("Search government entities") and immediately enumerates the filter dimensions and the tier coverage, which distinguishes it from the singular get_entity sibling. An agent can decide between this and get_entity without opening either 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?

Explains that every tier is searched rather than just the top one, and gives actionable follow-up behavior when scope is "direct_children" (narrow by state and search again). It stops short of naming sibling alternatives like get_entity or list_countries, so routing is inferred rather than explicit.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful context beyond that: results are compact records carrying jurisdiction slugs, and detail must be fetched via a separate tool. Pagination behavior is left to the schema rather than restated.

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, zero waste. Scope is front-loaded, filter options follow, and the routing hint to the detail tool is placed last where it is most useful.

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 five optional params, no output schema, and full schema coverage, the description supplies what the schema cannot: the domain taxonomy and the compactness of the return payload. It could say slightly more about what 'compact' omits, but an agent has enough 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%, so the baseline is 3, but the description earns a bump by naming the five domains that map onto the pillar enum values ("open records" -> "records", "open meetings" -> "meetings") and by clarifying that query matches name, citation, or jurisdiction. That mapping is not obvious from the bare enum.

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 (search government transparency laws) and immediately scopes it by enumerating the five domains covered. It also distinguishes itself from the sibling get_open_records_law, so an agent can tell the two apart without opening either 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?

Explains the available filter axes (country, pillar, query substring) and routes the agent to get_open_records_law when full open-records detail is needed. It gives clear positive guidance but no explicit exclusions, such as stating that this tool never returns full law text.

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 annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true), the description discloses critical runtime behavior: the request is validated, geocoded, classified, routed, and recorded; delivery has four distinct states (sent, held, dry_run, handoff) with a redirect_url for handoff; and it explicitly instructs 'Always check delivery.state'. It also reveals rate limiting and country restrictions, which are not part of the annotations. This adds substantial context that an agent needs to interpret the outcome, and it does not contradict any annotation.

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 organized: it leads with purpose and examples, then explains the backend processing, then details delivery states and the imperative to check delivery.state, and finishes with auth, rate limit, and supported countries. Every sentence adds new information; there is no fluff. The length is justified by the tool's complexity, though a more compact phrasing of the delivery states could tighten it slightly.

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 complex mutation tool with 8 parameters and no output schema, the description covers the essential behavioral context: how the request flows (validation → geocoding → classification → routing → recording), what delivery states to expect, auth requirements, rate limits, and supported countries. It explicitly mentions redirect_url for handoff. It does not detail error scenarios or the full response envelope, but the reminder to check delivery.state mitigates the missing output schema. Given the richness of the input schema, this is nearly complete.

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% — every parameter has a descriptive entry, including the address/lat-long alternative, country_code default, and service_type_id auto-classification. The description adds no additional parameter-level guidance beyond what the schema already provides; it only presents examples and high-level behavior. Baseline 3 is appropriate because the schema carries the full explanatory load.

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 opens with a specific verb-resource pair ('Submit a government service request') and concrete examples (pothole, broken streetlight, illegal dumping) that make the tool's function unmistakable. It clearly distinguishes itself from the read-focused siblings (get_*, search_*, list_*) which all retrieve or list data, whereas this is the only submission 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?

The description gives clear context on when to use the tool: when a citizen wants to file a service request. It also explains the delivery states and the need to check delivery.state, implicitly steering agents toward caution when the request is not immediately transmitted. However, it does not explicitly name alternative tools to use in other scenarios (e.g., when looking up a status, use get_cgj_report), though the sibling set makes the distinction obvious. It also outlines prerequisites (X-API-Key, rate limit, supported countries) that guide safe invocation.

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