mcp

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds valuable behavioral context: it explicitly states the authentication requirement (X-API-Key header), the rate limit (50 req/day shared with data.ungovr.org), and how to obtain a key. This goes beyond the annotations without contradicting them, providing critical operational details for correct invocation.

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 with no fluff. The main purpose is front-loaded, followed by essential operational requirements. Every sentence earns its place—no redundant information or 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?

For a simple detail-retrieval tool with one parameter and no output schema, the description provides the necessary invocation context: purpose, required input, authentication, and rate limit. It even hints at the response contents (findings, recommendations, responses). While it doesn't specify the exact return format, this is minor for such a straightforward tool and the description is otherwise 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?

The input schema covers the single parameter 'id' with a clear description ('Report ID (from search results)'), achieving 100% coverage. The description does not add any additional semantic detail about the parameter format or constraints, so it adds no value beyond the schema. 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 clearly states the action ('Get full details'), the specific resource ('a specific California Grand Jury report by ID'), and what content is expected ('findings, recommendations, and responses'). It is distinct from siblings like search_cgj_reports, which retrieves a list based on criteria, and get_entity, which targets a different resource type.

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 that this tool is used when you have a report ID, and the schema clarifies the ID comes from search results. It does not explicitly state 'use search_cgj_reports first to obtain an ID,' nor does it contrast with alternatives, but the implied workflow is clear enough for an agent to understand when to call this tool.

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 readOnlyHint annotation, the description discloses the exact return fields (name, type, website, parent, children, domain status, metadata) and highlights flexibility in hierarchy depth. This adds valuable context about what the agent can expect. It does not contradict annotations and covers the read-only nature adequately.

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 sentences with no filler. The primary action and resource are front-loaded, followed by concrete examples and scope clarification, then a concise list of return fields. Every sentence earns its place, making it easy for an agent to parse quickly.

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 simple, single-parameter read-only tool, the description covers all necessary guidance: what it does, how to specify the target (slug), what it returns, and its applicability at any hierarchy depth. Without an output schema, the explicit field list is sufficient. No missing information prevents correct invocation.

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 input schema already provides a thorough description of the slug parameter with examples, and schema coverage is 100%. The description adds examples and mentions broad hierarchy support, which reinforces but doesn't materially extend the schema's meaning. This meets the baseline for high schema coverage.

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 ('Get') and resource ('full details for a specific government entity') with a precise identifier (URL slug). It clearly distinguishes from sibling tools like search_entities, which perform searches, and list_countries, which list all entities. The hierarchy depth clarification (cities, school districts, special districts) further nests the tool's unique scope.

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 provides clear context for when to use the tool: when you have a specific slug at any hierarchy depth. It gives multiple examples but does not explicitly mention alternatives or exclusions. However, the implied use case (retrieve by known slug) is unambiguous, and the sibling names (e.g., search_entities) make the distinction obvious without needing explicit 'don't use when searching' 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?

The description discloses important behavior beyond the readOnlyHint annotation: it explains that any entity slug at any depth resolves to the governing parent law, and that the response includes 'resolved_from' when applicable. This adds non-obvious resolution behavior that the annotations do not cover.

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 efficiently structured, starting with the purpose, then the output fields, then input format and special cases. Each sentence adds necessary information without fluff; it's concise for the complexity it covers.

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 a single parameter and no output schema, the description lists expected return fields (name, citation, deadlines, fees, etc.), explains input resolution, and notes the special case of US federal FOIA and the 'resolved_from' field. This is comprehensive and leaves no critical detail missing for correct invocation.

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 parameter schema only describes a jurisdiction string; the description expands on this by providing multiple valid formats (e.g., 'us/ca', 'ie'), explaining that entity slugs at any depth are accepted, and giving the resolution rule. This adds significant semantic value 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?

States the exact purpose: retrieving the open records law (FOIA/RTI) for a jurisdiction, and lists the specific data returned. The description is specific about the resource and the inputs, and is clearly distinct from sibling search or scraping tools given the focus on open records law.

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?

Provides clear guidance on how to call the tool: accepts jurisdiction slugs or any entity slug, and explains resolution to a parent jurisdiction. However, it does not explicitly mention alternatives like search_transparency_laws or when not to use this tool, so it lacks explicit exclusions.

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 declare readOnlyHint=true, so the read-only nature is already disclosed. The description adds valuable behavioral context beyond the annotations: it specifies that the tool is public and requires no API key, and it describes the nature of the result (a full hierarchy). This goes beyond the baseline set by annotations and provides useful operational details, though it does not cover response format or potential size limitations.

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 sentences long, with no redundancy or filler. The core purpose is front-loaded in the first sentence, and the second sentence efficiently explains the product options and public access. Every word contributes value, making it optimally concise and well-structured.

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?

The tool is simple: one required parameter, read-only annotation, and no output schema. The description covers the essential context—what the tool returns (hierarchy of entities), the two product options, and authentication requirements. An agent can confidently select and call this tool without needing additional info, so the description is fully complete for its complexity.

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 the parameter with an enum. The description adds significant semantic meaning: it defines what each enum value ('request' and 'cgj') actually represents (worldwide coverage footprint vs. Civil Grand Jury coverage). This clarifies the mapping beyond the schema's bare 'Product id' description, enriching the agent's understanding of expected values and their effects.

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 ('Get') and resource ('full hierarchy of government entities where an UnGovr product is available'), and explicitly names the two product variants ('request' and 'cgj') with their meanings. This makes the tool's purpose unambiguous and differentiates it from siblings like get_cgj_report or search_entities, which focus on individual records or searches rather than coverage footprints.

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 provides clear usage context by explaining what each product value returns and stating that it is public and requires no API key. It implicitly indicates when to use this tool (to obtain coverage footprints) versus siblings, but it does not explicitly name alternative tools or state when not to use it. This is a clear context with no exclusions, fitting a score of 4.

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 only declare readOnlyHint=true and openWorldHint=false, which already indicate a non-destructive read. The description adds substantial behavioral context: response fields (as_of_date, confidence, stale flags) that the agent should check, the slug-resolution behavior that walks to the most specific jurisdiction and reports it in resolved_from, authentication requirements (X-API-Key header), rate limits (50 req/day shared with another service), and legal disclaimers. It also clarifies that this is research, not authorization. This goes well beyond the annotations and fully informs the agent about side effects and 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 approximately 120 words and each sentence serves a purpose: main function, resolution details, response-field warning, legal disclaimer, and authentication instructions. It is front-loaded with the core purpose and specific deliverables. While it is a bit long, the length is justified by the tool's complexity; it could arguably be tightened, but it remains efficient and well-organized.

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 tool's complexity—multiple legality dimensions, slug resolution, response metadata, and legal caveats—the description covers everything an agent needs to decide whether and how to call it: what it returns, how resolution works, what to check in the response, the auth requirement, and the disclaimers. Since there is no output schema, the description appropriately explains return values and safety implications. No critical information 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?

The input schema already covers the parameter (jurisdiction) with a description and example formats, so baseline is 3. The description adds valuable semantics about slug depth and resolution behavior: it accepts slugs at any depth and resolves to the most specific jurisdiction with data, populating resolved_from. This clarifies behavior not present in the schema, justifying an above-baseline score.

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 clear, specific verb ('Get') and resource ('scraping/access legality summary for a jurisdiction'), then enumerates exactly what it returns (verdict-level crawl policy, per-scenario access matrix, legality fields). It also names the sibling context indirectly by being jurisdiction-specific, distinguishing it from related tools like get_open_records_law without ambiguity. An agent can immediately understand the tool's function and scope.

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 context on when to use it (for a jurisdiction's scraping legality) and even points the agent to 'eu' for operator-specific obligations. It does not explicitly mention when NOT to use it or name alternatives, but the purpose is distinct enough that an agent would not confuse it with siblings. The lack of explicit exclusions is a minor gap given the clarity of purpose.

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, but the description adds meaningful context by specifying the nature of the data returned (entity counts and coverage metadata). It does not describe potential edge cases like empty responses or pagination, but for a zero-parameter list tool, this is minor. The description complements the annotations without redundancy.

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, well-structured sentence that front-loads the action and scope, then specifies the output details. Every word contributes; there is no filler or 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?

For a simple list tool with no parameters and no output schema, the description covers the essentials: what is listed and what data it includes. It doesn't mention limits or ordering, but the term 'all countries' implies completeness, and the simplicity of the tool makes this adequate.

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 are no parameters, so schema coverage is trivially 100%. The baseline for zero parameters is 4, and the description correctly avoids inventing parameter explanations. No additional semantic guidance is needed.

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 ('List'), a clear resource ('countries'), and a precise scope ('with government entity data in UnGovr'). It also specifies the output includes entity counts and coverage metadata, distinguishing it from sibling search tools like search_entities which target individual entities.

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 purpose implies usage (to get an overview of country-level coverage), but no explicit guidance is provided on when to use this tool versus alternatives like search_entities. It doesn't mention any exclusions or conditions, though the simplicity of the tool makes over-explanation unnecessary.

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=false, so the description doesn't need to repeat that. It adds useful behavioral context by stating the return format (grouped by category) and giving example categories (Infrastructure, Utilities, Parks). This goes beyond the annotation to clarify the output structure without contradicting the read-only hint.

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 concise sentences with zero filler. The verb and purpose are front-loaded, and the supported countries and return format follow logically. Every word earns its place.

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?

Despite lacking an output schema, the description states what the tool returns (service types grouped by category) and gives examples. It also covers the supported countries and the relationship to submit_service_request. For a simple list tool with one optional parameter, this is comprehensive.

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 schema description for the single parameter is 100% complete ('Two-letter country code: "us", "ie", or "gb" (default: "us")'). The description reiterates the supported countries but adds no new parameter-specific information beyond what the schema already provides. Since schema coverage is full, this gets the baseline 3.

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 uses a specific verb ('List'), identifies the resource ('service request categories and types'), and scopes it by country. It also explicitly states the tool's purpose: to discover valid service_type_id values for submit_service_request, which clearly differentiates it from that sibling and other listing tools like 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?

The description explicitly says 'Use this to discover valid service_type_id values for submit_service_request,' giving a concrete use case. It also lists supported countries (US, IE, GB), informing agents when the tool is applicable. This provides clear guidance on when to use it relative to the sibling submit_service_request.

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 only provide readOnlyHint=true, so the description carries the burden of behavioral disclosure. It adds substantial context: 'best-effort', authoritative vs. inference methods, the rationale for ignoring server/edge-node location, and rate limits/auth requirements. No contradiction with 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?

Five sentences, each serving a purpose: purpose and method, behavioral caveat, IP refusal, auth/rate-limit, and key acquisition. It is slightly longer than the bare minimum but every sentence earns its place; the core information is 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?

For a single-parameter tool with no output schema, the description fully explains the mapping logic (authoritative vs. inference), the main exclusions, and the required authentication and rate limits. An agent can decide to call this tool and know what to expect without needing more context.

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% for the single 'domain' parameter, including the rejection of IP addresses. The description adds the underlying rationale (server location is not a legal signal), which enriches the schema's literal constraint and helps the agent understand why.

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 ('mapping') and resource ('domain to jurisdiction'), and explicitly names its consumer ('get_scraping_law'). It also distinguishes itself by its unique purpose and method (authoritative for government domains, inference otherwise), making it easy for an agent to identify among siblings.

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 clearly says 'for feeding into get_scraping_law' and provides explicit exclusions: never uses server location and refuses IP addresses, with rationale. However, it does not explicitly name an alternative tool for IP-based jurisdiction, so the guidance falls short of a full when/alternative comparison.

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, so the description doesn't repeat that. It adds important behavioral traits: the API key requirement and 50 req/day rate limit, and the return structure ('report metadata (title, year, county, themes)'). It also points to a helper endpoint for valid counties, which affects call success. These go beyond the annotation, though it doesn't cover edge cases like no results or error handling.

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 brief and front-loaded. It opens with the primary action and filters, then the return type, then the authentication and county-list hint. Every sentence adds distinct information without redundancy. It is well-structured and avoids fluff, making it easy for an agent to parse key requirements quickly.

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 read-only search tool with all-optional parameters, the description covers the essential: what it searches, what it returns, authentication, rate limits, and how to get valid county names. It lacks explicit details on how filters combine (AND vs OR) and any details on sorting or default behavior, but those may not be critical given the schema and the 'and/or' phrasing. Overall, it's sufficiently complete for a well-behaved search endpoint.

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 each parameter has a description, so the baseline is 3. The description adds extra meaning by mapping the 'query' parameter to 'title keyword' and explaining how to obtain a valid county list (via the entity API). This supplements the schema's example county values and clarifies the intended use of the query parameter. It doesn't describe limit/offset beyond the schema, but the added context justifies a 4.

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 the tool's purpose: 'Search California Grand Jury reports by county, year, and/or title keyword.' It specifies the resource, the action, and the filter dimensions, and the return metadata. This distinguishes it from sibling tools like get_cgj_report (which likely retrieves a single report) and search_entities (which searches broader entity data). No ambiguity.

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 provides key usage context: it requires an API key with a rate limit and instructs how to obtain valid county names via a secondary API. This helps the agent prepare valid inputs. However, it does not explicitly contrast this tool with alternatives (e.g., 'use get_cgj_report to fetch a specific report'), so the agent must infer when this is preferred over other search tools. Still, the practical setup guidance is valuable.

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, so the safety profile is covered. The description adds substantial behavioral context beyond that: it specifies that searches cover every tier of government, explains the meaning of the 'scope' field ('full' vs 'direct_children'), and explicitly warns 'Unrecognised arguments are rejected, not ignored' – a behavioral trait not otherwise disclosed. This is exactly the kind of information an agent needs to use the tool correctly, and it does not contradict 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 well-structured and information-dense. It front-loads the purpose, then details the tiers covered, the return fields including the scope semantics, and concludes with a behavioral note about argument handling. Every sentence contributes valuable information; there is no filler or redundancy. While it's longer than average, the complexity of the tool justifies the length.

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 tool's complexity (multiple government tiers, 6 parameters, a 'scope' field with nuanced behavior) and the absence of an output schema, the description carries the full burden of explaining what the agent will receive. It covers return fields (slugs, types, website URLs) and the meaning of 'scope' for interpreting results. It also flags a potential edge case (rejection of unrecognized arguments). This makes the tool fully usable without additional context.

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 six parameters are individually documented. The description adds value by connecting parameters to behavior: it explains how 'state' narrowing interacts with the 'scope' field and hints that search results include slugs/types/URLs based on query parameters. This enriches understanding beyond the per-parameter schema lines, though it doesn't introduce fully new semantics for each parameter. The baseline is 3; the extra context lifts it to 4.

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 ('search'), a precise resource ('government entities'), and adds unique distinguishing details: it searches every tier of government (counties, cities, school districts, etc.) and returns slugs, types, URLs, and a 'scope' field. This clearly separates it from sibling search tools like search_cgj_reports and search_transparency_laws, which target different resources. The purpose is unambiguous and not a tautology.

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 explains when to use the tool (searching for government entities across jurisdictions) and provides operational guidance: the 'scope' field indicates whether all tiers were searched, and it advises narrowing by state and re-searching when scope is 'direct_children'. It does not explicitly name alternatives or state when not to use it, but the distinct purpose is clear enough that an agent can infer the appropriate context.

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, so the read-only nature is covered. The description adds behavioral detail by stating the return format (compact records with jurisdiction slugs) and implying a search/filter operation, which is useful beyond the annotations. No contradictions exist.

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 concise sentences. The first sentence presents the core purpose and scope, the second covers filters and output/alternative. No filler words; every clause contributes value.

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 search tool with all-optional parameters and no output schema, the description covers the domains, filters, and output nature (compact records with jurisdiction slugs) and points to the detailed alternative. It does not explain default ordering or pagination semantics, but those are inferable from the schema and do not block correct use.

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 all five parameters (limit, query, offset, pillar, country) are documented in the schema. The description reiterates that filtering is possible by country, pillar, and substring but does not add any new syntax or meaning beyond the schema's own descriptions. Thus, at the baseline of 3.

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 the tool searches government transparency laws and enumerates the five domains: open records, open meetings, fiscal transparency, digital accessibility, and oversight bodies. It also specifies the filters (country, pillar, substring) and distinguishes the output as compact records, separating it from the sibling get_open_records_law.

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 explicitly directs users to get_open_records_law when full open-records detail is needed, which is a clear alternative for a specific use case. It does not discuss other siblings (e.g., search_cgj_reports) but those cover different domains, so the guidance is sufficient for the primary context.

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.