OpenPublica

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

Annotations already mark readOnlyHint and openWorldHint, and the description adds meaningful behavioral context: category_tags are opaque UUIDs, topics have no fixed list, and date-less calls default to a window exposed as default_window_days. This goes beyond annotations without contradicting them.

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 compact—about four sentences—and front-loads the primary purpose before explaining rationale and usage. Every sentence contributes: purpose, why guessing fails, what to do with results, and scoping/default behavior.

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 output schema is present and annotations cover read-only/open-world behavior, the description supplies the essential workflow context: use it as a discovery step, scope optionally, and pass returned values downstream. Nothing critical is 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?

Schema coverage is 100% with clear descriptions for start_date, end_date, topic_limit, government_id, and government_ids. The description does not add detailed parameter-level semantics beyond summarizing that scoping can use government and/or date range, 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?

Description opens with a specific verb and resource: 'Discover the valid category and topic filter values before filtering a search.' It also explains the deeper purpose—opaque UUIDs and non-fixed topics—making it clearly distinct from sibling search tools.

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 explicitly says to call this first, that values cannot be guessed, and that discovered values should be passed into search_meetings_semantic or list_recent_meetings. This gives clear when-to-use and routing guidance to the correct sibling tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety and non-exhaustive nature are covered. The description adds useful behavioral context beyond annotations: results are prefix matches first, and the tool returns `account_id` values intended for further lookup. This is meaningful but not exhaustive; for example, it does not describe matching ambiguity or result ordering guarantees beyond prefix-first.

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 compact and front-loaded: the core purpose appears in the first sentence, usage context in the second, and the sibling distinction in the third. Every sentence is load-bearing and there is no redundant 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 read-only lookup tool with an output schema and full schema coverage, the description covers all necessary context: when to use it, what it returns, how the result is ordered, and how it differs from the coordinate-based sibling. No critical information is missing for an agent to select and invoke 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%: both `query` and `limit` are fully documented in the schema with types, defaults, constraints, and examples. The description reinforces that `query` is a city/state name, but does not substantially add semantic detail beyond the schema. A baseline score of 3 is appropriate because the schema carries the parameter documentation 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?

The description states a specific verb and resource: 'Resolve a place *name* to the governments OpenPublica tracks there.' It also distinguishes itself from `find_local_governments` by clarifying that this tool works from a name rather than coordinates. This makes the tool's role immediately clear and differentiated from 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?

The description gives explicit guidance: use it when you know a city/state name but not its coordinates, and prefer it over `find_local_governments` when starting from a name instead of latitude/longitude. It also explains the downstream action of passing the returned `account_id` to search/list tools, which clarifies why and when this tool is the right choice.

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

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

Annotations already declare readOnlyHint and openWorldHint. The description adds meaningful detail beyond those: it reveals the internal geocoding step, states that results include `account_id`s plus the resolved location, and explains that an empty `governments` list is a valid outcome when none are tracked nearby.

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 three short sentences with no filler, and the core action is front-loaded before the wrapper explanation and return-value semantics. Every sentence 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?

An output schema exists, so return-value structure does not need to be repeated. For a simple two-parameter lookup, the description adds the geocoding behavior, empty-list interpretation, and nearby-scope context an agent needs to interpret results 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?

The input schema covers 100% of parameters and already describes postal_code as a US ZIP code and limit as a 1-50 count. The description does not elaborate on either parameter beyond the schema, so the baseline of 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?

The description opens with a concrete action: 'Resolve a ZIP code to nearby tracked governments', naming both the input (ZIP) and the resource (governments tracked by OpenPublica). It is clearly distinct from the sibling find_governments_by_name, though it does not explicitly name alternatives.

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?

'Convenience wrapper: geocodes the ZIP, then finds...' implies the intended trigger is having a ZIP code and wanting the nearest tracked governments. It gives no when-not or alternative-routing guidance, so it stops short of a 5.

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 and openWorldHint annotations, the description adds concrete behavioral details: results include account_id, OpenPublica only covers limited US localities, and empty results mean no tracked government exists nearby. This meaningfully enriches the annotation-provided context.

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 with no wasted words: the first states the purpose, the second explains result value and downstream use, and the third addresses coverage limitations. The most important 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 low-complexity lookup with fully documented parameters, a 100% schema coverage, and an output schema, the description covers the key contextual needs: purpose, coordinate targeting, result semantics, and the meaning of an empty response.

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 baseline is 3. The description's 'near a coordinate' aligns with latitude/longitude but does not add extra parameter semantics or formatting details beyond what the schema already documents.

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: 'Discover which governments OpenPublica tracks near a coordinate.' It clearly differentiates from sibling tools like find_governments_by_name and find_governments_by_zip by focusing on coordinate proximity.

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 for the coordinate-based use case and explains how results feed into other tools via account_id, but it does not explicitly name alternatives or state when not to use this tool. The guidance is implied 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?

The annotations already convey read-only and open-world behavior, and the description adds a useful quirk: DC is reported separately as includes_dc, so the result should be read as 'N states and DC.' This goes beyond what annotations alone provide, with no contradiction.

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 no filler. The core purpose is front-loaded, and the DC reporting detail is isolated in the second sentence where it adds clarity without cluttering the main definition.

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 parameterless, read-only overview with an output schema, the description is complete. It tells the agent what the tool reports and the one non-obvious interpretation detail (DC handling), so nothing essential 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 tool has zero parameters, so parameter documentation is unnecessary. The description appropriately focuses on explaining output semantics instead, matching the baseline for a parameterless operation.

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: 'Get OpenPublica's overall coverage' and enumerates the exact metrics returned (total governments, states, meetings). This clearly distinguishes it from sibling tools that target individual governments or meetings.

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 that this is a platform-wide overview rather than a per-government query, and the DC nuance helps users interpret the result correctly. It does not explicitly name alternative sibling tools, but the zero-parameter design and 'overall' phrasing make the intended use unambiguous.

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 need to restate safety. It adds meaningful context about the availability key and its transcription-lint findings, which is a subtle behavioral nuance an agent needs to handle figures correctly. It stops short of describing the full return shape or error behavior, but that's acceptable for a read-only metadata tool.

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, each earning its place: the first states the core purpose, the second points to the sibling for reading, and the third gives a specific, important caveat about the availability key. Front-loaded and economical with 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?

For a single-parameter metadata getter with no output schema, the description covers the essential behavior: what it returns, how to read the actual content via an alternative, and a critical nuance about transcription-lint findings. It doesn't enumerate all possible metadata fields, but that isn't necessary for correct invocation. A solid, complete description for this level of 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?

There is only one parameter, document_id, and the schema already provides a 100% description (stating it comes from list_government_documents or search_documents). The description adds no additional semantics beyond what the schema provides, so a baseline of 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 it returns 'One document's metadata,' using a specific verb and resource. It directly distinguishes itself from read_document_pages by saying 'Use read_document_pages to read it,' making the division of responsibilities unambiguous.

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 explicitly names the alternative tool (read_document_pages) and specifies when to use that instead. It also provides a conditional usage instruction about the availability key, telling the agent to read it before quoting figures. This is precise, action-oriented guidance that leaves no ambiguity.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds that the result contains name, location, and meeting categories, but says nothing about permissions, tracking prerequisites, or response behavior beyond that.

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 clear, compact sentence that front-loads the operation and resource, then lists the return contents. There is no redundant phrasing 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 read-only, two-parameter tool with an output schema and annotations, the description plus schema is largely sufficient. It does not explicitly say how to obtain a government_id for untracked governments, but the sibling find_* tools make that inferable.

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 both parameters are already documented. The description adds only the qualifier that the government must be 'tracked', which slightly clarifies government_id but does not add meaningful parameter-level detail 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 uses a specific verb ('Get'), a clear resource ('a tracked government's profile'), and names the returned content ('name, location, and meeting categories'). It implies a distinction from sibling lookup tools like find_governments_by_name or get_government_stats, though it does not explicitly contrast them.

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 phrase 'a tracked government' implies this tool is for governments already known/tracked by ID, and the required government_id supports that. However, there is no explicit guidance about when to use this over siblings such as find_governments_by_name or get_government_stats.

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 annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context by specifying that the tool produces aggregate counts, a per-day map, and category breakdowns rather than raw records, and frames it as activity analysis over a window.

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 compact and front-loaded: it states the purpose first, then lists the return contents and a usage cue. Every sentence earns its place without redundant phrasing or boilerplate.

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 output schema exists, the input schema fully documents both parameters, and the description conveys the tool's scope and result shape, nothing essential is missing for an agent to select and invoke this 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%, and both parameters already have meaningful descriptions including the 'all' special value for government_id and the 1-365 range for days. The description does not add parameter-level detail, but it does not need to because the schema carries that 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?

The description uses a specific verb and resource: "Get meeting-activity stats for a government over a recent window", then enumerates exactly what is returned. This clearly distinguishes it from siblings like get_government_info, list_recent_meetings, and search_meetings_semantic.

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 by saying it is useful for questions like "how active has X been lately?". It does not explicitly name alternatives or state when not to use the tool, but the intent and appropriate scenario are evident from the description and the sibling tool names.

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 the description adds useful behavior: it discloses that include_transcript may return a long transcript and that a missing meeting yields an error object. These details go beyond the schema and annotations, though they are modest in scope.

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 tight sentences lead with the core purpose and then state the optional behavior and error case. There is no filler or repetition of schema contents.

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 read-only tool with fully described parameters and an output schema, the description covers what the tool returns, the optional transcript flag, and the failure mode. Nothing essential is missing for an agent to invoke it 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 fully documents meeting_id and include_transcript. The description adds value by explaining the transcript use case and the not-found error, but it does not need to do more given the complete 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 uses a specific verb and resource: it retrieves a single meeting's summary, topics, attendees, and optionally the transcript. This clearly differentiates it from sibling tools that search or list meetings, and the singular 'single meeting' avoids confusion with bulk operations.

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 communicates the main use case—retrieving one meeting's full details—and explains when to set include_transcript=true. It does not explicitly name sibling alternatives or state when not to use them, but the single-meeting framing plus the schema note that meeting_id comes from a search/list tool provides clear contextual 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 substantially extends the annotations by explaining the `covers` semantics, the meaning of each `status` value, and the conditional presence of `availability`. It also warns against false conclusions from missing entries and failed documents, aligning with and expanding on the openWorldHint.

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 opening sentence states the core purpose, and every following sentence adds disambiguating detail about result semantics. Formatting like bold `failed` and the `availability` condition makes the most important caveats easy to scan without wasted words.

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?

Even without an output schema, the description covers the critical output fields, the meaning of failure, and the conditionality of availability. For a read-only listing tool with two well-documented parameters, this is sufficient for an agent to select and interpret the call 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 adds meaningful context for `include_superseded` by explaining that superseded means a retired, non-searchable edition. This helps an agent understand exactly what including superseded documents entails.

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: 'List a government's adopted plan and budget documents.' This clearly distinguishes the tool from siblings such as get_document, search_documents, or list_recent_meetings by the object being listed and the adoption/budget 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 makes the intended use clear, but it does not explicitly name alternatives or state when not to use this tool versus search_documents, get_document, or get_coverage_overview. The usage context is strongly implied rather than explicitly routed.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context: results are ordered newest-first and support paging/filtering. It could say more about pagination behavior or result limits, but the schema and output schema already carry much of that detail.

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 with no filler. The core behavior and ordering are front-loaded, and the alternative-tool routing appears immediately after the main use case. Every sentence 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?

The tool has an output schema, fully documented parameters, and clear usage/routing guidance, so the description is largely complete. It could have explicitly pointed users to discover_meeting_vocabulary for valid topic/category_tag values, but the schema already contains those pointers, so the gap is minor.

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 baseline of 3 applies. The description adds a high-level mapping of filters ('government, type, topic, or date') to the parameters, but it does not add meaningful detail beyond what the schema already documents for each parameter.

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 ('Browse'), a clear resource (meetings), and the ordering ('newest-first'), plus four optional filter dimensions. It also distinguishes itself from search_meetings_semantic by positioning this tool as the browse/list option rather than the semantic-search option.

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 explicit use cases: 'what are the most recent meetings' and paging through a government's history. It also names the alternative tool, search_meetings_semantic, and says to prefer it for topical questions, giving clear when-to-use vs when-not-to-use 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 goes well beyond the readOnlyHint/openWorldHint annotations by explaining pixel-based transcription, how tables and scanned text are handled, that missing pages surface as marked holes instead of being dropped, and that covered may exceed requested. These are concrete behavioral traits 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?

The description is front-loaded with the core purpose and each subsequent sentence adds a distinct, necessary caveat about transcription fidelity, missing pages, or page-range reporting. There is no fluff or repetition of annotation/schema 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?

With no output schema, the description compensates by describing the markdown format, hole behavior, and covered/requested fields. It could be slightly more explicit about the exact return shape, but the operational guidance is sufficient for an agent to call it and interpret results.

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 documents all three parameters at 100% coverage, so the description adds no per-parameter detail. The mention of covered being wider is a useful output nuance, but it does not add semantic meaning to document_id, first_page, or last_page 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 first sentence names a specific verb and resource ('Read a page range of a document as markdown'), which clearly differentiates it from sibling tools like get_document or search_documents. No reading between the lines is needed to know what the tool does.

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 statement implies this tool is for extracting a page range as markdown, but the description never names alternatives or exclusion conditions, such as using get_document for a full document or search_documents for content discovery. Usage must be inferred rather than stated.

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

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

The description adds substantial behavioral context beyond the readOnly and openWorld hints: hits return short passages rather than full pages, first_page/last_page and source_url support citation, empty results do not imply absence of policy, and document_complete: false flags transcription findings requiring verification. No contradiction with annotations exists.

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 returns, then proceeds through citation guidance, search-type caveats, and a data-quality warning. Every sentence earns its place with 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?

Given the tool has no output schema, the description covers the essential return fields, how to use them, edge cases around empty results, and how to verify incomplete documents. It is sufficiently complete for an agent to invoke 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 coverage is 100%, so the baseline is 3. The description adds value by explaining that the query parameter should be phrased with literal plan terminology because the search is word matching, which meaningfully informs how the agent should construct the query.

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: 'Search adopted plan and budget documents, returning page-cited excerpts.' It also differentiates the tool by stating it is word matching, not semantic search, which separates it from semantic-search siblings like search_meetings_semantic.

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 explicit usage boundaries: it is word matching rather than semantic, so the agent should try terms a plan would actually use. It also routes the agent to read_document_pages for full-page context and to list_government_documents when results are empty, naming concrete alternatives and conditions.

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 readOnly/openWorld annotations, the description discloses important runtime behavior: results include relevance_score and keyword_score, and the degraded_to_vector flag means hits are semantic-only and must not be treated as exact-term matches. It also reveals that the response is a summary preview, not the full meeting.

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 front-loaded sentences with no filler: purpose, scoring/confidence caveat, narrowing options, and follow-up action. Every sentence earns its place and the most important guidance appears first.

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 rich output schema and readOnly/openWorld annotations already present, the description covers the remaining decision-relevant context: how to filter, how to interpret degraded results, and how to get full text. Nothing an agent needs in order to call this tool 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 schema carries most parameter meaning; the description adds value by framing how to narrow results (category_tag/topic from discover_meeting_vocabulary, date range, one or more governments) and warns about degraded keyword behavior. It does not add much beyond the schema for individual parameters like min_score and match_type, but the schema already documents those clearly.

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 first sentence names a specific verb and resource — 'Search OpenPublica meeting summaries' — and immediately disambiguates the search modes ('by meaning, exact terms, or both'). Calling itself 'the best default tool' for topic questions distinguishes it from siblings without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit default usage ('best default tool for ... X questions'), tells the agent where to get filter values (discover_meeting_vocabulary), and routes follow-up lookups to get_meeting. It does not explicitly state when to choose search_meeting_transcript or search_documents over this tool, so it stops short of full 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 mark this read-only, and the description adds useful behavioral details: server-side transcript fetching, returning only matching passages, approximate start/end timecodes, exact-match ranking with fuzzy fallback. 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?

Four sentences with no filler: purpose comes first, then usage context, behavior, and alternative routing. Each sentence contributes necessary information for correct tool selection and invocation.

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 description, complete input schema, and output schema together provide everything an agent needs: what the tool does, when to use it, how matching behaves, and the available parameters. No critical invocation context 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?

Input schema covers 100% of parameters with its own descriptions, so the baseline is 3. The description adds some behavior about matching and output passages, but it does not substantially enrich the meaning of individual parameters beyond what the schema already provides.

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') and resource ('one meeting's transcript') and clarifies the intended result is exact quotes/passages. This clearly distinguishes it from loading a full transcript via get_meeting.

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 explains when to use this tool: to pull direct quotations without loading a long transcript. It also names the alternative get_meeting(include_transcript=true) and states the preference condition.

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