OpenCityRecord

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: entries are returned oldest-first, each step carries the status recorded at that step, and the lifecycle state machine (pending → under-review → hearing → approved/denied) is disclosed. It stops short of discussing resolution failure behavior or pagination beyond the limit param.

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 purpose sentence, then clearly delimited WHEN / WHEN NOT / EXAMPLES blocks. Every line earns its place and nothing is repeated from structured fields unnecessarily.

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 re-explained, and annotations carry the safety profile. The description still supplies the ordering guarantee, the lifecycle vocabulary, and the sibling routing, leaving nothing an agent needs to call this correctly.

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

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

Schema description coverage is 100%, so q, city, limit, and application_id are all documented in the schema itself, including the q-ignored-when-id-set rule and the UUID format. The description adds examples showing q+city together but no semantics beyond what the schema already states, so the baseline 3 applies.

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

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

States a specific verb+resource: it returns how a development project moved through meetings, with named application types (rezone, subdivision, site plan, CUP, build). It also implicitly distinguishes itself from the policy-oriented sibling issue_timeline. An agent can tell this apart from search_meetings or issue_timeline without opening a 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 examples ('What's the status of the Silo Park development?') and WHEN NOT routing to issue_timeline for policy issues and search_meetings for quotes. The alternative selection conditions are spelled out rather than inferred.

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/idempotent/non-destructive, so the safety profile is covered; the description goes further by disclosing truncation of long records with a marker and by clarifying that a not-found error means a stale id rather than an access restriction. That error-semantics detail is context annotations cannot express.

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

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

Front-loads the core action, then uses short labeled sections (WHEN, WHEN NOT, EXAMPLES, error note) with zero filler. Every sentence conveys a constraint or a failure mode the agent needs.

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

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

An output schema exists, so return-value documentation is not required, yet the description still covers truncation, id provenance, and error interpretation. For a single-parameter read tool this is fully sufficient to 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% and there is only one parameter, so the baseline is 3. The description adds real meaning beyond the schema's terse 'An id returned by the search tool': the meeting:/doc: prefixes, the opacity of ids, and the prohibition on hand-constructing them.

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

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

States a specific verb (retrieve) and resource (full record) and explicitly maps the two id namespaces to two outcomes: 'complete meeting transcript (for meeting:… ids) or the full document text (for doc:… ids)'. This lets an agent distinguish it from search and search_meetings without opening a 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 ('after the search tool, to read a result in full before answering or citing') and WHEN NOT ('never construct one by hand; only use ids returned by search'), plus the remedy for the most likely failure mode. Nothing about selection 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 already declare readOnly, idempotent, openWorld, non-destructive, so the safety profile is covered. The description adds real behavioral value annotations cannot carry: search returns fragmentary segments, and fetch truncates at 40,000 characters from the START of a meeting, silently losing late-agenda content. It stops short of describing output shape or any rate limits, but the truncation caveat is exactly the kind of context that prevents a wrong tool choice.

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 one-line definition, then WHEN / WHEN NOT / EXAMPLES in scannable order. The anecdote about the FLOC fragment and the fetch truncation detail both earn their length by justifying the routing rule.

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 explained. Combined with annotations, a 100%-covered schema, and explicit routing guidance, everything an agent needs to invoke this correctly is present.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds the non-obvious mapping that the caller should pass start_seconds from a search_meetings hit as around_seconds, and provides two concrete invocation examples including before/after overrides. That is genuine meaning 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 — return the transcript passage surrounding a given moment, with speakers and timestamps — and immediately frames it against siblings (search_meetings hits, fetch). An agent can distinguish it from every other sibling without opening a 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 (always, before quoting or reasoning from a search hit) and WHEN NOT (to find something, use search_meetings; for a whole document, use fetch), plus a stated preference rule over fetch with the reason. Alternatives and selection conditions are 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds non-obvious runtime behavior: oldest-first ordering, per-entry meeting links, and the fallback where an ambiguous match yields issue: null plus a candidates list. That is real behavioral disclosure beyond structured fields.

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

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

Front-loaded with purpose, then WHEN/WHEN NOT, then examples; nearly every sentence earns its place. Slight redundancy in the two sentences about candidates, but no filler.

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

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

With an output schema present, return values need not be described, and the description still covers invocation guidance, resolution ambiguity behavior, and required pairings. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds resolution semantics the schema does not convey — the city-scoping rationale (same phrase means a different fight per city) and the candidates list even on a resolved issue. limit/issue_id precedence is left to 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 resource (an issue's chronological lifecycle) with concrete domain examples (zoning, housing, tax, road, park) and the shape of the return (raised → discussed → voted, oldest first, each entry linking to the meeting). It is clearly distinguishable from siblings like search_meetings and track_position.

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 examples, explicit WHEN NOT with named alternatives and the condition that selects each (person's statements → search_by_official, votes → track_position, one-off keyword → search_meetings). Also prescribes passing city with q.

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 read-only/idempotent/non-destructive semantics, and the description adds real behavior beyond them: the default roster excludes appointed members and staff, former officials require an explicit flag, and a stale official_id may point to someone no longer seated. The mention of role/status/term-date columns is mildly redundant given the output schema exists, keeping this just short of top marks.

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?

Well front-loaded with the most decision-relevant fact first (current roster by default), then WHEN/WHEN NOT, then examples. It is longer than strictly necessary because the include_former and include_appointed rationales are largely duplicated in the schema descriptions.

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 six-parameter, annotation-rich tool with an output schema, the description covers purpose, default filtering behavior, flag semantics, prerequisites, and sibling routing without needing to explain return values. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds intent-level meaning: include_former is framed as the historical/old-meeting switch, include_appointed as the planning-commissioner/staff switch. The EXAMPLES block demonstrates realistic parameter combinations (city+include_former, state+name_contains) that 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 — looking up who serves on a city council — and pins the default scope precisely (current elected officials, no appointed members, no staff). An agent can distinguish it from track_position and search_by_official without reading a 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 and WHEN NOT sections name the conditions and the alternatives: track_position for voting records, search_by_official for quotes. It also declares a prerequisite relationship (both siblings need a UUID this tool returns), which is exactly the routing information an agent needs.

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/idempotent/openWorld/non-destructive, so the safely-read profile is covered. The description goes well beyond that: it explains the opaque-id → fetch handoff, the URL-as-scope (not text) resolution rules, and that empty results mean no matches rather than a permissions failure with a retry-broader-keywords remedy — genuinely useful operational 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?

Long but organized into purpose, URL semantics, WHEN/WHEN NOT, and worked examples, with the core purpose front-loaded. The opening nominal phrase ('Anything about a city council, mayor, ...') is slightly list-heavy, but every section carries routing or interpretation value.

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

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

An output schema exists, so return-value details are not required, yet the description still explains the id→fetch workflow that makes the output usable. Combined with the URL-scoping rules and empty-result interpretation, an agent has everything needed to call and consume 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 coverage is 100% for the single query parameter, so baseline is 3. The description adds real meaning beyond 'Free-text search query' — how embedded OpenCity/state URLs are parsed as scope, and that a bare URL returns that scope's most recent activity — which materially changes how the agent should construct the value.

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

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

States a specific verb+resource ('Combined keyword search across public city-government meeting transcripts AND meeting documents') and enumerates the covered content types (ordinances, zoning, agendas, budgets). It explicitly distinguishes itself from search_meetings, search_documents, and list_officials, so an agent can separate 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?

Dedicated WHEN and WHEN NOT sections: prefers this tool for auto-routing clients and pasted OpenCity URLs, and explicitly routes to filtered siblings when they are available. Both the trigger conditions and the alternatives are named, leaving little 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 already cover the safety profile (readOnly, idempotent, openWorld), and the description adds context they cannot: a paid-plan gate (Resident and above), the concrete free-tier behavior ('upgrade hint, no data'), and the newest-first ordering of results. These are exactly the behavioral traits an agent needs before invoking.

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 core behavior, then cleanly sectioned into WHEN / WHEN NOT / EXAMPLES / REQUIRES. Every line carries routing or behavioral information; nothing is filler despite the length.

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

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

With an output schema present, return-value explanation is unnecessary, and the description covers everything else an agent needs: prerequisites (UUID from list_officials), paywall gating, alternative tools, and example calls. No material gap remains.

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 invocation-shape value the schema doesn't: it clarifies that omitting q returns full speaking history and shows two worked examples. It slightly duplicates the schema's official_id sourcing note, keeping it from a 5.

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

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

States a specific verb and resource — retrieving every transcript segment a specific elected official has spoken — and scopes it ('spoken', newest-first). It explicitly distinguishes itself from siblings by naming track_position and search_meetings, so an agent can route correctly without opening other 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?

Explicit WHEN ('what has X said about Y', reasoning, verbatim quote with timestamp) and WHEN NOT sections name the exact alternatives: track_position for votes, list_officials for the UUID prerequisite, search_meetings for non-elected speakers. It even explains *why* the alternative is correct (transcripts under-report voting records), which is unusually strong 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 cover the safety profile (readOnly, idempotent, non-destructive, open world), so the bar is lower — yet the description adds substantial non-obvious behavior: outcome vs. result semantics, amount_deferred meaning, that empty results reflect extraction lag rather than absence of decisions, that unofficial_decisions must not be counted in total or presented as official roll calls, and that every row carries a citation_url. This is exactly the kind of context annotations cannot carry.

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

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

Well front-loaded, with WHAT, WHEN, WHEN NOT and pitfalls in scannable blocks despite the length — justified by a 9-parameter tool with subtle semantics. Minor duplication: the 'Flock'/'Flocke' whole-word illustration restates the q schema description verbatim and could be dropped.

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 explained; the description instead covers the interpretive layer the schema cannot — coverage/coverage_note caveats, how to handle unofficial_decisions, and where to verify a specific one (get_transcript_window). Complete for the tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema documents every parameter thoroughly. The description adds value through worked example invocations that demonstrate non-obvious combinations (outcome:'tabled' with a free-text subject; min_amount_usd with basis:['award'] and since), plus the outcome-not-result guidance. It repeats the whole-word matching rule already in the schema, so it is not a clean 5.

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

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

States a specific verb and resource ('search recorded motions, votes and amounts') and immediately scopes it: the structured record of what a body decided, drawn from approved minutes. It also names the sibling it is not ('not people talking... use search_meetings'), so an agent can route without opening a 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 section with natural-language queries, an explicit WHEN NOT section naming three alternatives (search_meetings, track_position, application_timeline) with the condition selecting each, and a documented fallback (search_documents) when coverage is empty. 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 already cover readOnly/idempotent/openWorld, but the description adds real behavioral context: the meaning of an empty `hits: []` (no text match, not missing access), the retry guidance, and the note that `limit` results are spread across cities and meetings. It stops short of documenting result shape or any auth/rate constraints.

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

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

Front-loaded and scannable with labeled WHEN / WHEN NOT / EXAMPLES sections, and every block earns its place. The opening clause is stylistic rather than the operational verb, which pushes the actual function into the second sentence.

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 spelled out, yet the description still explains the empty-result case that an agent would otherwise misreport. With 4 well-documented parameters and full sibling routing, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it with three worked examples that demonstrate realistic `q` + `cities` combinations and the newline `q` placeholder pattern for the sibling tool. It does not add format or enum detail the schema lacks, but the examples are genuinely additive.

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 (keyword search across extracted document text) and enumerates the covered artifact types (agendas, minutes, staff reports, packets, attachments, ordinances, resolutions). It explicitly distinguishes itself from the sibling search_meetings by contrasting the written record with the spoken transcript.

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

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

Provides explicit WHEN and WHEN NOT blocks naming the alternative tool (search_meetings) and the conditions that select it, including the metadata-only case with the `q` placeholder trick. Nothing about tool selection 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 already declare readOnly/idempotent/non-destructive, so the added value here is real behavioral context: result spread across cities and meetings, the `official_id` field appearing only when a speaker matches an elected official, attribution limits for unnamed residents, and an explicit instruction that `hits: []` means no match rather than missing access. The last point prevents a concrete failure mode the annotations never mention.

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 what is searched, then WHEN/WHEN NOT, then examples, then the empty-result rule — a sensible priority order. It runs long and duplicates the `since` and `limit` rationale already present in the schema descriptions, which is the main waste.

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 shape needn't be explained, and the description covers everything else an agent needs: scope, filters, routing to sibling tools, the meaning of an empty hit list, and the citation caveat. Nothing required 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 the schema already documents all seven parameters and the baseline would be 3. The description still adds value through worked examples that show parameters being combined (cities + since + officials_only, meeting_types, and a bare-query case), plus a cross-reference pointing elected-only filtering to list_officials. Some of the `since` rationale restates the schema text verbatim, which caps this below a 5.

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

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

States a specific verb (keyword search) and resource (meeting transcript segments) and immediately scopes what counts: city council, planning-commission, and other public city meetings. It names the differentiating siblings — search_by_official for a person's speaking history and search_documents for ordinance text and PDFs — so an agent can route correctly 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 block gives the triggering question shapes ('What did people say about X?'), and the WHEN NOT block names the two alternatives with the condition that selects each. Conditional guidance on `since` for 'recent' questions and `officials_only` for 'what did OFFICIALS say' closes the remaining 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 cover read-only/idempotent, but the description adds non-obvious context: a paid-plan requirement, a warning not to reconstruct voting records from transcript segments (they under-report because they capture discussion not tally), and the claim that this is the only tool returning votes. These are genuinely valuable behavioral facts beyond the structured data.

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 headline plus tightly organized WHEN/WHEN NOT/EXAMPLES sections; sentences are dense but each carries routing or caveat information. Slightly long, with some repetition between prose and examples, keeping it short of a 5.

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, annotations covering the safety profile, 100% schema coverage, and explicit cost/limitation caveats, an agent has everything needed to select and invoke it correctly. The dependency on list_officials for the UUID is called out.

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

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

Schema description coverage is 100%, and the schema for topic/since/until already states optionality and the 'omit for complete record' guidance — so the description largely restates rather than extends it. The example payloads add marginal value by showing valid argument combinations, but the baseline of 3 applies when the schema does the heavy lifting.

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

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

Opens with a concrete verb+resource ('The voting record of one elected official') and immediately scopes the return ('roll-call votes ... plus expressed stances, chronological'). It explicitly distinguishes itself from siblings — search_by_official for statements, whats_changed/search_meetings for topic-wide queries, list_officials for the ID.

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?

Has explicit WHEN / WHEN NOT blocks with literal example questions mapped to argument patterns ('How has X voted on housing?' → pass topic) and named alternatives for each adjacent case. No inference is required to route correctly.

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

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

Goes well beyond the read-only/idempotent annotations by disclosing plan-gated behavior (free plans return `redacted: true` with no member attribution) and a real interpretive trap: most decisions are unanimous voice votes with `roll_call: false` and no tally, yet must still be reported. This is exactly the kind of behavioral context an agent cannot derive from 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?

Purpose is front-loaded, followed by WHEN / WHEN NOT and a single concrete example, with zero filler. Every sentence carries a distinct load: scope, plan behavior, edge case, routing, and a usable call snippet.

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 three-parameter, output-schema-backed read tool, the description covers everything an agent needs: scope, selection criteria, sibling routing, plan gating, and a data-interpretation warning. Return values are already covered by the output schema, so nothing material is missing.

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

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

Schema coverage is 100%, so city, since, and limit are already fully documented in the schema; the description adds no syntax, format, or edge-case meaning for them. The worked example demonstrates a valid call but does not extend parameter semantics, so the baseline 3 applies.

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

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

States a specific verb and resource — the 'changeset of council activity in a city since a date' — and enumerates exactly what it contains (decisions with tallies, issues discussed, development-application status changes, paid-plan member votes). It further distinguishes itself from siblings by naming track_position and issue_timeline as the wrong tools for single-entity queries.

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

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

Explicit WHEN section gives sample user questions ('What did the council do in the last two weeks?') and an explicit WHEN NOT that routes single-person or single-issue longitudinal queries to track_position / issue_timeline. The alternative and the condition selecting it are both stated.

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