OpenPublica

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

Annotations already cover safety (readOnly, non-destructive), and the description adds real behavioral context: values are opaque UUIDs, topics have no fixed list, and calls without explicit dates fall back to a recent window returned as default_window_days. This is genuinely useful beyond the annotations, though not exhaustive.

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 the action and rationale, then the downstream routing and scoping note. Every sentence carries distinct information with no padding.

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 an output schema present, return values need not be restated, and all five parameters are documented in the schema. The description supplies the missing 'why' and 'when', leaving nothing an agent needs to call 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 coverage is 100%, so the baseline is 3, but the description adds meaning: it explains the government/date scoping intent and the default-window behavior when start_date/end_date are omitted, which the schema alone does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Discover the valid category and topic filter values') and explains why the tool exists (values cannot be guessed). It clearly differentiates itself from the search/list siblings it feeds into.

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 says to 'Call this first' and names the downstream alternatives ('search_meetings_semantic' / 'list_recent_meetings') with the exact arguments to pass. When-to-use is 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context: results carry an `account_id`, prefix matches are ranked first, and the output feeds downstream search/list tools. It omits edge cases such as zero-match behavior and result ordering ties, so it stops short of 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?

Two sentences, zero waste: the resolution behavior and the routing rule each get one sentence, with the name-vs-coordinates distinction front-loaded before the sibling comparison.

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 values need not be enumerated, yet the description still calls out the `account_id` field that makes the tool useful as a pipeline step. For a 2-parameter lookup with full schema coverage and annotations, nothing an agent needs 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. The description goes beyond the schema by disclosing query matching semantics (prefix matches ranked first) and by naming the returned `account_id` as the value to hand to other tools, which is meaningful parameter/flow context the schema does not carry.

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 ('Resolve') and resource ('place name' → 'governments OpenPublica tracks'), and the sibling list makes the distinction sharp: find_governments_by_zip, find_local_governments, and get_government_info all cover adjacent territory. An agent can route without opening any schema.

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

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

Explicit when-to-use ('when you know a city/state name but not its coordinates'), explicit alternative ('Prefer this over find_local_governments'), and the condition that selects between them (name vs latitude/longitude). Nothing is left to inference.

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

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

Annotations cover the safety profile (readOnly, non-destructive, openWorld). The description adds real value beyond them: that it internally geocodes, resolves proximity, returns account_ids plus resolved location, and that an empty list means none tracked nearby yet. That last point is a genuinely useful behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short paragraphs, front-loaded with the purpose, with no wasted sentences. The wrapper explanation and empty-result note each earn their 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?

Given an output schema exists, return-shape explanation is not required, yet the description still clarifies what is returned (account_ids, resolved location) and the empty-result edge case. An agent has everything needed to call and interpret 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 coverage is 100%, so both postal_code (US ZIP example) and limit (1-50) are fully documented in the schema. The description adds the resolved-location/account_id semantics but no additional parameter syntax beyond the schema, 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?

Specific verb (resolve) and resource (ZIP to nearby governments), and explicitly labels itself a convenience wrapper combining geocoding plus proximity lookup. It is clearly distinguishable from siblings like find_governments_by_name or find_local_governments.

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 it geocodes then finds nearest tracked governments, giving a clear usage context. It does not explicitly say when to prefer find_governments_by_name or find_local_governments instead of this ZIP route, so no explicit exclusion/routing is offered.

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 readOnly, openWorld, and non-destructive. The description adds genuinely new behavioral context: OpenPublica's limited US-locality coverage and the fact that an empty result means nothing is tracked nearby yet. That coverage caveat is exactly the kind of detail 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?

Three short sentences, front-loaded with the purpose, followed by the practical use of the return value and the coverage caveat. 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?

An output schema exists, so return values need not be enumerated, yet the description still highlights the one field that matters (account_id) and the coverage caveat. For a simple geo-lookup tool, nothing an agent needs 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 description coverage is 100%, so longitude, latitude, and limit are already fully documented (including range bounds). The description adds no syntax or format detail beyond the schema, 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 and resource ('Discover which governments OpenPublica tracks near a coordinate'), and the coordinate-based mechanism implicitly separates it from the by_name and by_zip siblings. It stops short of naming those siblings explicitly, so it is clear but not fully differentiated.

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 downstream workflow: the returned account_id can be passed to other tools to scope results to a city or board. It also clarifies what an empty result means. It does not state when to prefer this over find_governments_by_name or by_zip.

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, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful interpretive caveats beyond that: counts do not establish completeness, searchability or freshness, and DC is reported separately as includes_dc. This tells the agent how to read the result, not just that it is safe.

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 that are front-loaded with the core definition and then the caveats. No filler, though the line breaks make it slightly choppier than a single tight paragraph.

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 the description needn't enumerate return fields; it supplies the interpretive framing an agent needs. The only gap is the absence of routing guidance relative to the many sibling 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?

The tool takes zero parameters, so there is nothing to document and the baseline of 4 applies. The schema is an empty object and the description correctly does not invent parameter behavior.

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: it returns estimated stored-record totals, and explicitly frames this as coverage at the storage level rather than publication-filtered coverage. It is clear enough to distinguish from a publication-oriented sibling, though it never names which collection the records belong to.

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 clarifies the scope of the counts (stored-record, not publication-filtered) which implicitly tells the agent when this is the right metric, but it names no alternative tool and gives no explicit when/when-not guidance against siblings like get_government_stats or get_document.

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 meaningful behavior beyond that: it explains the optional availability key and what its problems list means, which the agent cannot infer from annotations or schema. It does not cover what fields the metadata contains, keeping it below 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?

Two short paragraphs, front-loaded with the purpose and the sibling redirect, then the conditional availability note. No wasted words, though the second paragraph is slightly dense.

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 metadata tool, the description covers purpose, the sibling boundary, and the one non-obvious behavioral detail (availability problems). No output schema exists, so field-level return detail is absent, but the essential calling 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?

The single document_id parameter is fully described in the schema (100% coverage), including its source, so the description does not need to repeat it. Baseline 3 applies because the description adds nothing about the parameter 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 a specific verb and resource: retrieving one document's metadata, and explicitly redirects to read_document_pages for the actual content. This distinguishes it from its closest sibling. The only shortfall is that 'metadata' is not itemized, but the scope is still clear.

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 names the alternative (read_document_pages) and the condition that selects it (to read the document). It also gives a conditional check on the availability key before quoting figures, which is actionable routing 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds little behavioral context beyond naming the returned fields; it doesn't mention the optional weekly digest, auth needs, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with zero waste that states the verb, resource, and returned fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values needn't be explained, and annotations cover safety. However, for a tool with an optional weekly-summary flag and open-world scope, the description is thin on when to include the summary and on any access prerequisites.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both government_id and include_weekly_summary. The description does not add any parameter meaning 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 ('Get') and resource ('a tracked government's profile') and enumerates the returned fields (name, location, meeting categories). It is distinguishable from siblings like find_governments_by_name or get_government_stats, though it doesn't explicitly name an alternative.

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 word 'tracked' implies the government must already be in the system, but the description never states when to use this versus find_governments_by_name or get_government_stats, nor any prerequisites. Usage is only weakly 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 readOnly, non-destructive, openWorld, so the safety profile is covered. The description adds that results are aggregated over a window and what is aggregated, but adds nothing on caching, result size, or 'all' corpus behavior beyond what the schema states.

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, purpose front-loaded before the return summary. The output enumeration is slightly list-like but each item earns its place by signaling what an agent can extract.

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 an output schema present, the description needn't describe return values, yet it cleanly conveys purpose, scope, and use case. Nothing essential is missing for correct invocation, though cross-tool routing detail is absent.

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 (days, government_id) are fully documented in the schema, including the 'all' sentinel and 1-365 range. The description's 'recent window' wording adds no syntax or default detail beyond that.

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 (meeting-activity stats for a government) and enumerates the three outputs (total count, per-day map, category breakdown). This is clearly an aggregate-stats tool distinct from list/search siblings, though it never names them explicitly.

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 a concrete use case ('how active has X been lately?') that tells the agent when to reach for this instead of a list/search tool. It lacks explicit when-not-to-use or named alternatives, keeping it 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavior the annotations do not: it returns an error object when the meeting is not found, and it warns that the transcript fetch can be long.

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 short sentences, front-loaded with the core purpose, followed by the single optional-flag instruction and the error behavior. 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?

With a full output schema, return shape need not be explained, and annotations carry the safety profile. The description covers the error case and the optional transcript, leaving only minor gaps such as whether 'topics' differ from the transcript and any rate/length limits.

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 a baseline of 3 applies. The description goes beyond the schema by explaining the intent of include_transcript — retrieving the complete transcript specifically for direct quotation — which tells the agent why it would pay the size cost.

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 a single meeting') and names the payload ('full AI summary and topics'), which cleanly separates it from list_recent_meetings and the search_* siblings. An agent can tell what it will receive 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 conditional for the optional flag ('Set include_transcript=true to also retrieve the complete transcript... for direct quotation'), which is real usage guidance. But it never states when to call this tool versus the search/list siblings or where the required meeting_id comes from in the description itself (that hint lives only in the schema).

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?

With annotations already covering read-only and non-destructive, the description goes well beyond them by decoding the `status` values (`converted` searchable, `superseded` stored but unsearchable, `failed` held but unreadable) and the conditional `availability` block. The `failed`-is-not-absence warning and `source_url` fallback are exactly the non-obvious traits an agent needs to avoid misreporting.

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?

Purpose is front-loaded, then interpretation rules follow in short paragraphs that each earn their place (covers, status, availability). It is slightly longer than strictly necessary but avoids filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly assumes the burden of explaining the returned fields and does so thoroughly for the fields that matter most. Ordering and pagination are left unstated, a minor gap for a list 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%, so both parameters are already documented, and the description adds only indirect context through its explanation of the `superseded` status. Baseline 3 is appropriate when the schema carries the parameter definitions.

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 with a narrow scope: listing a government's adopted plan and budget documents. An agent can tell this apart from generic document search, though it never names the sibling it differs from (e.g. search_documents).

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 guidance is about interpreting output rather than choosing between tools: it warns not to treat missing element names as unpublished and explains that `failed` is not evidence of nothing published. There is no explicit when-to-use or when-not-to-use versus sibling tools like search_documents or get_document.

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, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds the newest-first ordering and paging behavior, which is useful context beyond the annotations, but doesn't cover rate limits or result size beyond what limit implies.

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 short sentences, front-loaded with the core behavior (newest-first browsing) before the alternative route. 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?

Output schema exists, so return values need not be explained. Annotations cover safety; the description covers ordering and the alternative tool. Complete enough to call correctly, though it could mention that filters are combinable or vendor the vocabulary dependency.

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 all seven parameters documented in detail including date format, tag provenance, and government_id source. The description mentions the filter dimensions but adds no syntax or examples 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?

States a specific verb and resource ('Browse meetings newest-first') with explicit filter dimensions, and contrasts against the topical alternative `search_meetings_semantic`. An agent can distinguish it from the semantic search sibling 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 explicit when-to-use cases ('what are the most recent meetings', paging a government's history) and names the alternative for topical questions. The routing decision is fully specified.

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 real behavioral traits: content is transcribed from rendered pixels (so tables/scans become text), untranscribed pages appear as marked holes the agent should surface rather than skip, and the returned `covered` range may be wider than the requested range. These are non-obvious traits an agent cannot get from the annotations or 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?

Three short paragraphs, front-loaded with the core action, then behavior, then the citation rule. Every sentence carries operational weight — no filler, no 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?

With no output schema, the description carries the return-format burden and does so: markdown output, hole markers for failed transcription, and the `covered` field semantics. Combined with the schema's 40-page clamping note, an agent has everything needed to call and interpret 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%, so the baseline is 3, but the description adds meaning about how the requested page inputs relate to the returned coverage ('covered may be slightly wider than what you asked for; cite the page numbers in covered, not requested'). That is genuine semantic value for interpreting first_page/last_page behavior, above the schema baseline.

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 precise verb+resource+scope: 'Read a page range of a document as markdown.' That distinguishes it from whole-document retrieval, and the second paragraph clarifies it works from rendered pixels. However, it never names sibling tools like get_document or search_documents to make the boundary explicit, so differentiation is inferred rather than stated.

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 context is implied (you call this to read pages of an already-known document) and there is useful operational guidance on handling transcribed holes and on citing `covered`. But there is no explicit statement of when to prefer this over get_document or search_documents, and no stated prerequisites beyond the schema's document_id provenance hint.

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 confirm readOnly/no-destructive/openWorld, and the description goes well beyond them: it discloses that matching is lexical not semantic, that only currently-served documents are covered, that `document_complete: false` flags transcription findings requiring verification, and the exact hit fields returned. This is unusually rich behavioral 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?

Purpose and return shape are front-loaded, and each subsequent paragraph addresses a distinct concern (context reading, citation, lexical matching, empty results, transcription warnings). It is longer than strictly necessary but almost every sentence carries actionable 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?

There is no output schema, yet the description fully specifies the relevant hit fields (text, first_page, last_page, source_url, document_complete) and how to act on them. Given the tool's complexity and the absence of structured return documentation, this is 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 coverage is 100%, so the schema already documents query, limit, and government_id, giving a baseline of 3. The description adds useful semantic framing for the query parameter (word matching, use terms a plan would actually use) but adds nothing for limit or government_id.

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 a specific resource (adopted plan and budget documents) and the shape of the return (page-cited excerpts). This clearly separates it from siblings like search_meeting_content and search_meetings_semantic without needing to open any schema.

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

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

Explicitly routes the agent: use read_document_pages with the hit's `first_page` for context, and check list_government_documents when results are empty or documents may not have been read. It also warns that an empty result is not evidence of absence, which is a when-to-trust-this condition.

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, openWorld), and the description adds real behavioral context: one card per meeting, native pagination with no total, previews that may be absent and are not timestamp evidence, and relevance lag with matches across untimed boundaries. These are genuine operational caveats an agent would not get from the annotations alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded, which is good, but the caveat lines are terse fragments that read as internal jargon ('do not establish timestamps', 'match across untimed boundaries') and are hard to parse. Size is reasonable; clarity of the later sentences is not.

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 10 parameters at 20% description coverage and an output schema present, the description correctly focuses on search semantics rather than return shape. Still, the many undocumented filter parameters and the absence of any sibling differentiation leave meaningful gaps for a moderately complex search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 20% – just query and cursor carry descriptions. The description touches the source parameter tangentially ('Source transcripts...'), but leaves topic, category_tag, government_id, government_ids, start_date, end_date, and limit entirely unexplained in both places. It does not compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Search public meetings once across metadata and stored transcript text.' That is clear enough for an agent to know what the tool does. However, it never names or contrasts with the obvious siblings search_meetings_semantic and search_meeting_transcript, so the agent must infer the boundary itself.

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?

There is no explicit when-to-use, when-not, or alternatives guidance. The closest thing is an oblique line, 'Source transcripts searches stored text, including meetings without timed proof,' which hints at a mode but does not tell the agent when to pick this tool over search_meetings_semantic or search_meeting_transcript.

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 safety (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds genuinely useful behavior: results carry a relevance_score and only a preview, with get_meeting needed for the full text. It stops short of describing result ordering or pagination beyond the schema's limit.

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 dense sentences, front-loaded with the core purpose and the disambiguating sibling name, followed by result shape and filtering/navigation hints. No filler or redundant 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?

With 10 parameters, an output schema, and full annotation coverage, the description supplies the missing routing and result-shape context an agent needs. Only minor gaps remain (ordering of results, how min_score interacts with relevance_score in practice), which the schema largely covers.

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 every parameter (limit, min_score default 0.4, date formats, government_ids overriding government_id) is already documented. The description only restates the filter categories at a high level and adds no syntax or defaults 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?

The description gives a specific verb+resource+mechanism ('Find AI summaries by meaning'), and immediately contrasts with the sibling that does lexical search ('use search_meeting_content for stored words'). An agent can distinguish this from search_meeting_content and search_meeting_transcript without opening any schema.

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

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

It names the alternative (search_meeting_content) and the condition selecting it (stored words vs meaning), describes how to narrow results (government, category_tag, topic, dates), and routes to get_meeting for the full summary. Both the routing decision and the follow-up path are 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 readOnly/openWorld/non-destructive, and the description adds genuinely useful behavior: results may lack a literal preview, timing is not resolved, and it is not a local scan or fuzzy ranking. These are non-obvious traits not derivable from the schema or 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?

Three short sentences, front-loaded with the core action before the caveats. Every sentence carries content, though the 'separate local scan or fuzzy passage ranking' clause is slightly oblique and requires interpretation.

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 an output schema present, return values need not be fully explained, and the description still flags the optional-preview behavior and the retrieval alternative. The 'currently public meeting' restriction is stated, leaving little an agent needs to call 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 already documents both parameters (query as analyzed words or quoted phrase, meeting_id as canonical id). The description adds no parameter-level syntax or format detail beyond the scope constraint, 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?

The first sentence gives a specific verb and resource (stored-text search) plus a scope constraint ('inside one currently public meeting'), which is more precise than the bare name. It does not explicitly distinguish itself from the close siblings search_meeting_content or search_meetings_semantic, so an agent must infer the split.

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 names one alternative with a condition ('use get_meeting(include_transcript=true) for full source retrieval'), which is real routing guidance. However, it never says when to prefer this over the other meeting-search siblings, leaving the main selection decision implied.

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