Read-only public data on Georgia's prisons: population, facilities, deaths, contraband, statutes.
Scored across 23 tools
Most tools target a clearly distinct dataset or resource, and descriptions add filters and caveats that further disambiguate. Minor overlap exists between get_system_statistics (which includes population/mortality aggregates) and the dedicated get_population_snapshot and get_mortality_data tools, and between get_historical_series and the more specific get_parole_statistics, but boundaries are largely explained.
Nearly every tool follows a clean verb_noun snake_case pattern (get_*, list_*, search_*), e.g. get_facility, list_facilities, search_site. Pluralization and noun forms are predictable throughout, with no mixing of camelCase or vague verbs.
23 tools is on the heavy side, but the server spans genuinely distinct domains (contraband, drugs, Facebook, facilities, staff, historical series, mortality, OCGA, parole, settlements, system stats, search). Each tool maps to a separate dataset or discovery function, so the count is justified rather than padded.
The surface covers the full research workflow: discovery (list_*, search_*), retrieval (get_*), and orientation (get_gps_guide, get_page, list_intelligence). Coverage of major datasets is strong; only minor gaps remain (e.g., no dedicated tool for comparing facilities side by side or for discovering contraband item categories without filters).
Incidents from GDC's own published contraband arrest reports (2010-present, ~1,600 incidents,
including reports that survive only in the Internet Archive; page: gps.press/contraband-data/):
one row per incident with GDC's wording verbatim, the people as GDC categorised them
(staff / officer / contract staff / visitor / civilian), the items, whether an arrest was
reported, and the GDC source URL. Filters: facility slug (e.g. dooly-state-prison), year,
actor_category (staff | visitor | civilian | officer | gdc_staff | contract_staff),
item_category (cellphone, tobacco, marijuana, methamphetamine, ...), arrest_made (yes|no|unstated),
q (text match). Structured rows name staff, officers and contract staff as GDC printed them; other people appear by category and role only. The narrative is GDC's own text.
Rows are long (a few thousand characters each): per_page defaults to 5 and is capped at 20;
use page to continue and the filters to narrow. total is the number of matches.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | ||
| page | No | ||
| year | No | ||
| facility | No | ||
| per_page | No | ||
| arrest_made | No | ||
| item_category | No | ||
| actor_category | No |
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 real behavioral context beyond them: rows are a few thousand characters each, per_page defaults to 5 and is capped at 20, and `total` is the count of matches. It also discloses data-shaping behavior (verbatim GDC wording, PII handling for staff vs other actors).
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?
Dense but front-loaded, opening with what the tool returns and its provenance before filters and pagination. Every clause carries information, though the run-on filter and PII exposition sentences could be tightened slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains row shape (long narrative rows, verbatim wording), the naming convention for structured actors, the total count, and pagination limits — enough for an agent to consume 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?
With 0% schema description coverage across 8 params, the description fully compensates: facility slug with example, year, actor_category with valid values, item_category with examples, arrest_made (yes|no|unstated), q as text match, plus page/per_page semantics. Nothing needed to call the tool correctly is left undocumented.
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 (contraband incidents from GDC's published arrest reports), the row granularity, the date span, and the exact provenance including Internet Archive survivors. An agent can distinguish this from get_contraband_summary and the other siblings 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?
Gives clear operational guidance: use filters to narrow, use `page` to continue, and implies the tool is for enumerating individual incidents. It does not explicitly say when to prefer get_contraband_summary over this tool, which is the main missing routing cue.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summaries of GDC's published contraband arrest reports. by = year | facility |
actor-category | role | item-category | stats. Optional facility slug / year filters (not for
stats). Counts arrests as GDC reported them; GDC's own running tally is not used because it is
not a consistent series across copies of the same report.
| Name | Required | Description | Default |
|---|---|---|---|
| by | No | year | |
| year | No | ||
| facility | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by explaining that counts are based on GDC's published reports rather than GDC's running tally, and why that choice was made. This goes beyond what annotations provide.
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 first clause states what the tool returns, and the rest adds high-value grouping, filtering, and data-source caveats. There is no filler or redundant restating of the title.
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 summary tool with three optional parameters and no output schema, the description covers the main elements an agent needs: source data, grouping options, filters, and a data-quality caveat. It stops short of specifying the exact output shape or allowed category values, but the annotations cover safety and the overall complexity is modest.
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 0%, so the description carries the burden for parameter meaning. It compensates well by enumerating valid `by` values and clarifying that facility/year are optional filters, while noting they do not apply to `stats`. However, it does not enumerate valid values for actor-category, role, or item-category, nor explain defaults like year=0, so it is not fully complete.
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 identifies the tool as producing summaries of GDC contraband arrest reports, with an explicit list of grouping keys (`by` = year | facility | actor-category | role | item-category | stats). This makes it easy to distinguish from siblings such as get_contraband_incidents, which presumably returns individual incidents rather than aggregated counts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool — when a summary/count of contraband arrests is needed — but it never names alternatives or explicitly says 'use get_contraband_incidents for raw incidents.' It does provide a usage constraint ('Optional facility slug / year filters (not for stats)'), but that is more parameter guidance than tool-selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Admissions to Georgia prisons on drug offenses for the latest published report year, broken down by sex, age band and related measures.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only, idempotent, and non-destructive, so the description does not need to repeat that. It adds useful context by noting the data covers the latest published report year and specific demographic breakdowns, but it does not disclose details like data source, update cadence, or exact return structure.
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, tightly written sentence front-loads the core subject ('Admissions to Georgia prisons on drug offenses') and efficiently adds temporal scope and breakdown dimensions. There is no filler or repetition of the tool name or title.
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 zero-parameter report-retrieval tool with no output schema, the description supplies sufficient context: geographic scope, topic, time period, and breakdowns. It could be slightly more precise about what 'related measures' includes or how the latest year is identified, but the tool is simple enough that this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema covers all of them by default, so the baseline is 4. The description adds value by indicating that the returned data is organized by sex, age band, and related measures, giving the agent a clearer idea of the fixed output dimensions.
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 identifies a specific resource: admissions to Georgia prisons on drug offenses. It adds temporal scoping ('latest published report year') and output breakdowns ('sex, age band and related measures'), making the tool's purpose unambiguous and distinct from siblings like get_length_of_stay or get_population_snapshot.
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 usage context is implied: an agent can infer this tool is appropriate when drug-admission statistics for Georgia prisons are needed. However, it does not explicitly state when not to use it or mention any alternative tools, leaving the routing decision to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What people on Facebook are saying about Georgia's prisons: public posts in the Ga. Prisons Exposed
group and comments on GPS's own Facebook posts that GPS kept (families, formerly incarcerated people,
former officers, advocates), newest first, each with its author, date, link and label:
'first-hand or inside account' (something specific that happened, seen or lived by the author or told
by someone inside), 'opinion', 'idea for change', or 'news retold'. Filters: q (words), facility (a
prison name, e.g. "Telfair"), days (default 30, max 365), label (account | opinion | idea | news),
limit (default 10, max 60). counts gives items and people per label for the whole match.
These are the authors' own views and accounts, never GPS findings: attribute and link every quote.
Names of people in custody and GDC numbers are removed before the data leaves GPS.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | ||
| days | No | ||
| label | No | ||
| limit | No | ||
| facility | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, idempotent, non-destructive, non-openWorld), and the description adds context they cannot: data provenance ('the authors' own views and accounts, never GPS findings'), a mandatory attribution obligation, PII redaction ('names of people in custody and GDC numbers are removed before the data leaves GPS'), and the semantics of the `counts` output. These are real behavioral traits beyond the 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?
Purpose and source are front-loaded, and the filter list with defaults reads as a compact reference block. The four label definitions are necessary but make the prose dense and slightly sprawling; a bulleted form would scan faster, though nothing is truly wasted.
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 enumerating returned fields (author, date, link, label) and explaining the `counts` aggregate. Combined with full filter semantics, ordering, provenance and privacy handling, an agent has everything needed to call and interpret 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 0%, so the description carries the full burden and does so: it defines q, facility (with an example, 'Telfair'), days (default 30, max 365), label (enumerating account | opinion | idea | news) and limit (default 10, max 60). Every parameter's meaning, default and bound is supplied where the schema gives nothing.
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 (public Facebook posts and comments) and pins down the exact data source: the Ga. Prisons Exposed group plus GPS's own posts. The label taxonomy and the 'newest first' ordering let an agent distinguish this from siblings like search_quotes or search_site 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?
The framing ('What people on Facebook are saying about Georgia's prisons') and the full filter list give a clear sense of when this tool applies, and the attribution note ('attribute and link every quote') constrains use. However, no alternative tool is named and there is no explicit when-not guidance despite 22 siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One facility's full public record plus its most recent state health inspection, if GPS has one.
`slug` is the facility's gps.press slug, e.g. 'macon-state-prison'. Use
list_facilities to find it.| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral nuance via the conditional 'if GPS has one,' indicating the inspection data may not always be present. This goes beyond what annotations alone convey, though it could mention behavior for unknown slugs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long with no wasted words. The core purpose is front-loaded, and the parameter guidance is concise and directly actionable. The example and cross-reference to list_facilities 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?
For a simple single-parameter read tool, the description covers what is returned (full public record and most recent inspection), the parameter semantics, and how to discover the parameter value. With annotations covering safety and idempotency, there are no major gaps 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?
The schema only defines 'slug' as a string with no description. The tool description compensates fully by explaining that slug is the facility's gps.press slug, giving a concrete example ('macon-state-prison'), and directing users to list_facilities to find valid values. This is exactly the kind of semantic enrichment the schema lacks.
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 a specific verb ('Get') and resource ('one facility's full public record plus its most recent state health inspection'). It distinguishes itself from sibling tools like get_facility_staff_roster or get_population_snapshot by focusing on the full record plus inspection, not a specialized subset.
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 concrete usage context: fetch a single facility's comprehensive record and its latest inspection. It also advises using list_facilities to find the slug, which is helpful. It does not explicitly enumerate when not to use the tool versus each sibling, but the scope is clear enough for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Staff headcount and list for one GDC facility, from a GDC-produced roster.
Answers "how many staff work at X", "how many officers work there", "list the
staff at X". `slug` is the facility slug, e.g. 'dooly-state-prison' (use
list_facilities to find it).
`title` optionally filters by job title. GDC abbreviates heavily: correctional
officers appear as "Correctional Ofc", clerical staff as "Admin Support" or
"Admin Assistant". Try both the plain word and the abbreviation.
ALWAYS report the `observed` date alongside any figure from this tool. A roster
is a single-day observation, not a statement about who works there today.
A zero for a role is a finding about the roster rather than missing data: the
roster holds no nursing, physician or dental titles anywhere in GDC, which is
consistent with medical staffing being contracted rather than directly employed.
Do not assert that reason as established fact.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| limit | No | ||
| title | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal a safe, read-only, idempotent operation, and the description adds substantial behavioral context: the roster is a point-in-time observation, zero values are meaningful findings rather than missing data, and the medical-staffing interpretation should not be asserted as fact. No contradiction with the readOnly/idempotent annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place: front-loaded purpose, concrete examples, useful abbreviation guidance, and critical interpretation caveats. It is well structured and contains 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?
Despite having no output schema and minimal input schema, the description gives the agent enough to invoke the tool correctly and interpret results: what the data source is, what questions it answers, how to find the slug, how titles are abbreviated, and how to handle dates and zero counts. The only slight gap is the limit parameter behavior, but the overall context is complete for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates well by explaining slug with an example and clarifying title-filter behavior including GDC abbreviations. It omits any explanation of the limit parameter, though limit is optional and has a default, so this is a minor rather than critical 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?
The description clearly states the tool returns a staff headcount and list for one GDC facility from a GDC-produced roster, and gives concrete example questions it answers. It distinguishes itself from broader tools by emphasizing the single-facility scope and the roster source.
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 tells the agent to use list_facilities to find the slug, explains how the title filter works with abbreviations, and instructs the agent to always report the observed date. It also warns that the roster is a single-day observation, not a statement about current staffing, which is clear when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GPS's orientation file for AI clients (llms.txt) — READ THIS FIRST.
Carries the things the data tools cannot: which figure to lead with when two are
defensible, how to label budget figures, the exact date of the DOJ findings report,
and the claims GPS has publicly corrected and will not repeat. Roughly 2,000 words.
The datasets give you accurate numbers. This is what keeps the sentence around the
number accurate too.| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only, idempotent, and non-destructive. The description adds meaningful context beyond that: it is roughly 2,000 words, contains editorial guidance, and includes claims GPS has publicly corrected and will not repeat. This clarifies expected behavior and content without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the most important instruction, READ THIS FIRST. It efficiently lists the types of guidance contained in the file. The final metaphorical sentence earns its place by clarifying the tool's complementary role to the data tools.
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 zero-parameter, read-only tool with no output schema, the description is complete enough. It tells the agent what the file is, why it matters, roughly how long it is, what guidance it contains, and where it fits relative to sibling data 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 has zero parameters, so the schema fully covers parameter expectations and the description has no parameter burden. The baseline of 4 applies because there is nothing for the description to clarify.
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 identifies the tool as retrieving GPS's orientation file for AI clients, specifically the llms.txt file, and states READ THIS FIRST. It distinguishes itself from sibling data tools by explaining it carries interpretative guidance rather than raw dataset numbers.
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 an explicit directive to use this tool first, and explains that it carries context the data tools cannot, such as which figures to lead with and which claims to avoid. The final paragraph reinforces the division of labor: datasets provide accurate numbers; this tool keeps the surrounding wording accurate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dated changes to Georgia parole and sentencing rules and the court rulings on them, 1908-present (the 1979 guidelines grid, the 1994-95 Sentence Reform Act, the 1998 90% policy, the 2005 Fulton order voiding it, the 2006 and 2008 changes, HB 1176 in 2012), each with its source and quote. topic = parole | sentencing | court.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | ||
| to_year | No | ||
| from_year | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, closed-world behavior, so the safety profile is covered. The description usefully adds that each event comes with its source and quote and that the dataset spans 1908-present, but says nothing about result volume, pagination, or filtering behavior.
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 a dense parenthetical of examples that earns its space by pinning down scope. It is long but not padded; every named event adds disambiguation 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?
Adequate for a read-only lookup whose annotations cover safety, but with 0% schema coverage and no output schema, the description leaves the year-filter semantics and expected result behavior undocumented.
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 0%, and the description only supplies the topic values (parole | sentencing | court), which is genuinely useful since the schema defines no enum. It adds nothing about from_year/to_year semantics, including what the default 0 means.
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?
Names a specific verb+resource (dated changes to Georgia parole/sentencing rules and court rulings) and enumerates the exact historical events covered, so an agent can distinguish it from get_historical_series or search_historical_data 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?
Usage is implied by the content scope but the description never states when to choose this over the many sibling historical tools (get_historical_series, list_historical_series, search_historical_data). No exclusions or prerequisites are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One GPS Historical Data series by year: every value with the source's own label, the source
(publisher, title, page, URL) and the exact quote it was checked against, plus the series'
definition BREAKS (never read one trend across a break). Get slugs from list_historical_series,
e.g. deaths-bjs-state-prisons, homicides-gdc-via-doj, los-pct-released-on-parole-gdc,
population-yearend-gdc-series, deaths-gps-registry (live). CSV: add ?format=csv to the REST URL.
Values are paged (limit default 25, offset); narrow with from_year/to_year/category/subgroup.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| limit | No | ||
| offset | No | ||
| to_year | No | ||
| category | No | ||
| subgroup | No | ||
| from_year | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive, so safety is covered. The description adds real behavioral context beyond that: paging via limit (default 25)/offset, the CSV variant trick, that every value carries its source citation and checked quote, and the analytic warning never to read a trend across a definition break.
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 the tool returns, then slug sourcing, then paging/filtering, then format hint. Dense but every clause carries information; the parenthetical breaks warning and the slug examples are justified. Slightly packed in the first sentence but not wasteful.
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 helpfully enumerates the return shape (values, labels, publisher/title/page/URL, exact quote, breaks) and paging behavior. There is no auth or rate-limit note, but for a read-only idempotent lookup tool the coverage is sufficient 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 0%, so the description must compensate, and it largely does: it explains limit default 25, offset, the from_year/to_year/category/subgroup narrowing axes, and gives concrete slug examples. It doesn't clarify what category/subgroup values are valid or how the slug is formatted beyond examples, leaving some gaps.
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: retrieves one GPS Historical Data series by year, with the exact payload contents (values, source citation, quote, breaks). It also implicitly distinguishes itself from list_historical_series by telling the agent where to get slugs, so the two siblings are separable 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?
Explicitly routes the agent to list_historical_series for slugs and tells it how to narrow results (from_year/to_year/category/subgroup) and request CSV. It doesn't state when NOT to use it (e.g. multi-series or keyword discovery cases), so it falls short of a full when/when-not/alternative rubric.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
How long people actually serve in Georgia, by offense and year: average sentence, years served, percentage of sentence served, share released on parole, and the lifer figures — plus the trend summary.
`offense` is a case-insensitive substring of GDC's offense name (e.g. 'murder',
'burglary', 'drug'; also the four-digit offense code). With no `offense` the
all-crimes series is returned. `year` is the calendar year of release (e.g.
'2023'). Both filter on this server. Rows are newest year first and paged:
`limit` (default 30) and `offset`; `matched_offenses` lists what `offense`
matched. `summary_only` returns just the summary block.| Name | Required | Description | Default |
|---|---|---|---|
| year | No | ||
| limit | No | ||
| offset | No | ||
| offense | No | ||
| summary_only | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive, non-open-world behavior, so the safety profile is covered. The description adds genuinely useful operational context beyond that: filtering happens server-side, rows are returned newest-year-first, results are paged, and `matched_offenses` reports what the offense filter matched.
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 payload the tool returns, followed by compact parameter semantics and paging behavior. Every clause carries information; there is no filler or repetition 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 does the work of describing return content: the metric fields, `matched_offenses`, and the paging shape. It slightly underspecifies pagination boundaries (no maximum `limit`, no total-count signal), but an agent can call the tool correctly from what is given.
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 0%, so the description must carry all five parameters, and it largely does: `offense` is a case-insensitive substring of the GDC offense name and also accepts a four-digit offense code; `year` is the release calendar year; `limit` (default 30) and `offset` page the rows; `summary_only` returns just the summary block. It also documents the empty-string default behavior for `offense`.
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 dataset and enumerates exactly what is measured: average sentence, years served, percentage served, parole-release share, lifer figures, and a trend summary. It is far more than a restatement of the name. It does not, however, explicitly distinguish itself from nearby siblings such as get_parole_statistics, which also covers parole-release information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: the description explains that omitting `offense` yields the all-crimes series and that `year` scopes to release year, which tells the agent how to shape a call. But it never says when to choose this tool over alternatives like get_parole_statistics or get_system_statistics, and no exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deaths in GDC custody since 2020 — yearly and monthly counts, cause-of- death breakdown, deaths by facility, facility type, security level and age.
With no arguments this returns the whole published document plus a list of
its sections. `section` returns one section by name (e.g. 'YEARLY
STATISTICS', 'DEATHS BY FACILITY'); `year` filters the yearly and monthly
lines to that year; `facility_contains` filters the by-facility ranking AND returns that facility's cause-of-death breakdown.
Filters are matched against the published lines, which is why the matching
lines are returned verbatim rather than re-tabulated.| Name | Required | Description | Default |
|---|---|---|---|
| year | No | ||
| section | No | ||
| facility_contains | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by explaining the no-argument return (whole document plus section list), how filters are matched against published lines, and why results are returned verbatim rather than re-tabulated. This adds meaningful behavioral context that the readOnly/idempotent hints do not cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is densely informative with no wasted sentences: overview first, then behavior with no args, then each parameter with its unique effect. The line about verbatim matching justifies an otherwise surprising behavior, earning 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?
With no output schema, the description appropriately explains the return behavior (whole document, sections, verbatim filtered lines) and data coverage. It covers all incoming parameters and the no-argument case, leaving no major gaps for an agent 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 0%, so the description fully carries the burden of parameter documentation. It explains each of the three parameters ('section returns one section by name', 'year filters the yearly and monthly lines', 'facility_contains filters by-facility ranking AND returns cause-of-death breakdown') and gives concrete examples of valid section names.
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 identifies the tool's verb and resource: 'Deaths in GDC custody since 2020' plus the data dimensions (yearly/monthly counts, cause-of-death breakdown, facility, facility type, security level, age). This precise scope distinguishes it from sibling tools that cover other domains like contraband, population, or parole.
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 strong guidance on how to use the tool, including the no-argument case, section selection, year filtering, and facility_contains behavior. It does not explicitly name alternatives or exclusion conditions, but the specific topic and param explanations make appropriate usage clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full text of a section of the Official Code of Georgia Annotated from GPS's public mirror.
`section` is the bare citation without the 'O.C.G.A. §' prefix, e.g.
'9-14-42', '42-5-2', '17-9-4'.| Name | Required | Description | Default |
|---|---|---|---|
| section | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds 'from GPS's public mirror' to signal source/authority and 'full text' to signal scope, but doesn't describe error behavior or response format. 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?
Three short sentences total: the first states the tool's behavior, the second gives the key formatting rule, and the third provides examples. No filler, and the most important context is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, read-only, idempotent getter, the description covers the essential context: what the tool returns, where the data originates, and how to format the citation. It stops just short of a perfect score because there is no output schema and no mention of edge cases such as missing or invalid sections.
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 0%, and the description fully compensates by defining the `section` parameter as a bare citation without the 'O.C.G.A. §' prefix and giving three concrete examples. This is exactly the level of detail an agent needs to construct a valid call.
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 'Full text of a section of the Official Code of Georgia Annotated', specifying a clear verb, resource, and scope. Unlike sibling tools focused on facilities, contraband, or mortality, this one targets a distinct legal-code resource, so an agent can distinguish it without extra inference.
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's no explicit when-to-use or alternative guidance, but the description clearly implies it is for retrieving full OCGA section text via GPS's mirror. It provides the citation format for the one parameter, though it doesn't state when to prefer this over search_site or get_page.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read any gps.press page as clean Markdown.
Every page on the site has a Markdown twin at the same URL with `.md` appended;
this fetches it. Accepts a full URL, a path, or a bare slug — '/vision2027/',
'vision2027', and the full https URL all work, with or without '.md'.
Covers articles, data pages, campaign pages and the intelligence briefings
(intelligence/facility/{slug}, intelligence/issue/{slug}).
Long pages are truncated; use `offset` and `limit` to page through one. Pair with
search_site() to find a page, then read it here rather than guessing its contents.| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| limit | No | ||
| offset | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior. The description adds valuable behavioral details beyond that: it fetches the .md twin, accepts URL/path/slug forms, truncates long pages, and supports offset/limit pagination.
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 four focused sentences with the core purpose front-loaded. Every sentence adds value: accepted inputs, page coverage, truncation behavior, and a sensible pairing workflow.
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 tool with no output schema, the description covers return format, accepted inputs, page scope, and pagination. An agent has enough context to select and call it correctly, including knowing to search before fetching.
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 0%, so the description carries the burden and it largely succeeds. It fully explains the path parameter's accepted input forms and explains how offset and limit are used for pagination, though it does not define bounds or special values.
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 names the exact verb 'Read' and the resource 'gps.press page as clean Markdown', then enumerates the page types it covers. This clearly differentiates it from sibling tools that fetch specific datasets.
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 provides an explicit workflow: pair with search_site() to find a page, then read it here rather than guessing contents. It does not spell out when not to use this tool versus other sibling fetchers, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Georgia parole decisions by year — the series GPS assembled from the State Board of Pardons and Paroles' own annual reports, with the metric definitions and the instruments note that says how they were built.
`metric` (exact name from the `metrics` list, e.g. 'cases_considered'),
`from_year` / `to_year` (fiscal years) filter the series. Paged: `limit`
(default 100 rows) and `offset`.| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| metric | No | ||
| offset | No | ||
| to_year | No | ||
| from_year | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds real context beyond that: the data is assembled from primary annual reports, comes with metric definitions and an instruments note, and is paged with a default of 100 rows. It still omits auth requirements and any pagination termination behavior, keeping it from 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 compact blocks: a front-loaded statement of what the series is, then a terse parameter/paging note. Every clause earns its place, with no restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-output-schema, five-parameter read tool, the description supplies the identity of the series, its provenance, and all parameter meanings, which is enough to call it correctly. A little more on valid year ranges or how to discover the metrics list would make it fully self-contained.
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 0%, so the description must carry the burden, and it largely does: it explains that metric takes an exact name from the metrics list, that from_year/to_year are fiscal years, and that limit/offset implement paging with a 100-row default. It does not state accepted syntax or bounds for the year parameters, which leaves a small 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?
The description names a specific resource with scope and provenance: 'Georgia parole decisions by year' from the State Board of Pardons and Paroles' annual reports. It is clearly a read of a curated time series rather than a computed statistic, which subtly distinguishes it from siblings like get_system_statistics or get_mortality_data. It stops short of explicitly differentiating itself from those siblings by name, so a 4 is appropriate.
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 tells the agent how to use the parameters ('metric' must be an exact name from the metrics list; from_year/to_year filter; limit/offset page) but offers no when-to-use guidance or naming of an alternative. Usage is implied by the parameter explanations rather than stated as selection criteria among the ~22 sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Latest GDC population snapshot (the weekly 'Friday report'):
total_in_gdc_custody (every GDC bed type, including probation detention
centers and RSAT), the jail backlog, and the facility-type components.
The total is the ONLY population figure; the components are parts of it,
not alternative totals.| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and non-destructive behavior. The description adds the weekly cadence, the scope of included bed types, and a critical semantic caution that components are parts of the total, not alternative totals. This adds value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, focused sentences with no filler. The key resource is front-loaded and the semantic caveat is placed immediately after the component list, earning 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?
For a zero-parameter read-only tool with rich annotations, the description sufficiently explains what data is returned and how to interpret the total. A slight gap is the lack of an explicit return shape for the jail backlog and facility-type components, but the description is still complete enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and 100% schema coverage, so there is nothing for the description to explain. The baseline for zero-parameter tools is 4, and no parameter ambiguity exists.
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 ('Latest GDC population snapshot') and names the exact contents: total_in_gdc_custody, jail backlog, and facility-type components. It is clearly distinguishable from sibling tools focused on contraband, facilities, mortality, and other data.
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 establishes clear context by identifying the weekly 'Friday report' and latest snapshot, making it obvious when an agent needs current population custody data. It does not explicitly name alternatives or exclusions, but the semantic warning about the total being the only population figure provides useful guidance on interpretation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What Georgia has paid to settle prison death and injury claims — the 'What Georgia Pays' analysis of state settlement records, returned as the published markdown.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds that the tool returns the published markdown of a specific analysis rather than a live or filtered query result, which is meaningful behavioral context beyond the annotations. It does not describe potential limitations, but the bar is lowered by the strong annotation set.
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 a single sentence with no filler. The core subject is front-loaded, and the output-format qualifier is placed at the end. Every phrase contributes useful 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?
For a zero-parameter, read-only tool returning a fixed published markdown, the description is complete. It states what data is covered and what form the result takes. No additional information is necessary 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?
The tool has zero parameters and the empty schema already documents this fully. The description correctly avoids inventing parameter details. The baseline of 4 for zero-parameter tools 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 names a specific resource: Georgia's settlement payouts for prison death and injury claims, and explicitly identifies the output as the 'What Georgia Pays' published markdown. This makes the tool's purpose unambiguous and distinguishable from sibling data-retrieval tools like get_mortality_data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when an agent needs Georgia settlement data for prison death and injury claims. However, it gives no explicit routing guidance or exclusions relative to sibling tools, so the selection decision is left mostly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Headline statistics for the Georgia prison system: population, mortality, demographics, facility counts, releases and health measures, with the update date and data source GPS assembled them from.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful transparency by stating that the output includes the update date and the data source that 'GPS assembled them from', giving the agent context about data provenance and freshness that the annotations do not provide.
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 a single sentence that front-loads the core purpose and uses a compact list for the data categories. It avoids redundant restatements of the tool name. The only minor issue is the slightly awkward phrasing 'GPS assembled them from', but it does not waste 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?
Given the tool has no parameters, no output schema, and annotations that cover safety and idempotency, the description supplies the essential missing context: what data categories are included and that update date and data source are part of the result. This is sufficient for an agent to understand what the tool returns without over-explaining.
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 no parameters, so there is no parameter ambiguity to resolve. The description compensates by outlining the returned content categories, which helps the agent understand what to expect even though the schema is empty.
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 resource ('Georgia prison system') and a clear verb ('get') tied to 'headline statistics', then enumerates the covered categories: population, mortality, demographics, facility counts, releases, and health measures. It is distinct enough from sibling tools like get_population_snapshot or get_mortality_data by framing itself as a system-wide aggregate, though it does not explicitly name those 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?
The phrase 'headline statistics' implies this is the tool for a broad system-level overview, providing some usage context. However, it does not explicitly state when to use this tool versus more specialized sibling tools such as get_population_snapshot or get_mortality_data, so the agent must infer the intended selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Georgia prison facilities with location, operator, security level, capacity, population, warden and latest food-safety score.
Optional filters are applied to the public list after it is fetched:
facility_type (e.g. 'State Prison', 'Transitional Center', 'County
Prison'), county, name_contains, and active_only. Responses are paged:
`limit` (default 25) and `offset`; `next_offset` says where the rest begins.| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| county | No | ||
| offset | No | ||
| active_only | No | ||
| facility_type | No | ||
| name_contains | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safety profile (readOnly, idempotent, non-destructive), so the description's job is to add context — and it does: filters are applied to the already-fetched public list rather than server-side, responses are paged with a 25 default, and next_offset marks the remainder. That post-fetch filtering nuance is genuinely non-obvious and valuable.
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 tight sentences: what is returned first, then filter semantics, then paging. No filler. Slightly dense but front-loaded and every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description steps in by listing returned fields and exposing next_offset for pagination, so an agent can consume results. Minor gaps remain (county vs name matching semantics, case sensitivity) but 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 description coverage is 0%, so the description must carry the parameters, and it names every one: facility_type with concrete example values ('State Prison', 'Transitional Center', 'County Prison'), county, name_contains, active_only, plus limit (default 25) and offset. No enum or format details for county/name_contains matching remain unexplained, so it compensates well without being exhaustive.
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 specific verb+resource ('List Georgia prison facilities') and enumerates the fields returned, so the agent knows exactly what this yields. It is implicitly distinct from the singular sibling get_facility, but the description never names that sibling or state the singular/plural split, so it stops short of a 5.
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 documents how filters behave and how paging works, which tells the agent how to drive the tool, but it offers no when-to-use/when-not guidance or explicit alternative routing (e.g. 'use get_facility for one facility'). Usage is implied by the filter list rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GPS Historical Data (page: gps.press/historical-data/): the catalog of yearly series on Georgia's prisons, 1925-present. Each series is ONE publisher's measure (GDC and Board of Corrections annual reports, the Bureau of Justice Statistics, the State Board of Pardons and Paroles, DOJ, the AJC, UCLA Law Behind Bars, the GPS mortality registry) with its definition, coverage and caveats. Topics: deaths, homicides, suicides, violence, use_of_force, weapons, parole, time_served, lifers, population, capacity, budget, escapes, staffing. Never splice two publishers' series into one trend.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds valuable behavioral context around series semantics and publisher isolation, but says nothing about pagination, default behavior, or result shape. With annotations doing the safety work, 3 is appropriate.
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 text is front-loaded with the resource identity and page reference, then caveats. It is somewhat long and the embedded URL and parenthetical publisher list add bulk, but every sentence carries domain 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?
For a single-parameter read-only listing tool with no output schema, the description supplies the domain framing, publisher list, topic vocabulary, and the key interpretive caveat. The main gap is the undocumented topic parameter's exact filtering semantics.
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 0% and the single 'topic' parameter has no description, so the description must compensate. It does so partially by enumerating valid topics (deaths, homicides, parole, lifers, etc.), but it never states that these map to the topic argument or what the empty default returns. Useful but not fully compensatory.
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 concrete resource: a catalog of yearly series on Georgia's prisons from 1925 to the present, enumerating the publishers and the topic coverage. An agent can tell it apart from get_historical_series (a single-series fetch), though the description never explicitly says 'list' and never names that sibling.
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 provides a domain rule ('never splice two publishers' series into one trend') and clarifies that each series is one publisher's measure. However, it gives no explicit when-to-use guidance relative to get_historical_series or search_historical_data. Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List GPS intelligence briefings — per-facility and per-issue analyses.
`kind` filters to 'facility' or 'issue'; `contains` filters on the slug.
Read any of them in full with get_page(), e.g.
get_page('intelligence/facility/dooly-state-prison').
Both kinds are discovered from GPS's public intelligence index pages; if the issue
hub cannot be read, `issues_note` says so in the payload.| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| contains | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description earns credit for adding provenance ('discovered from GPS's public intelligence index pages') and a failure-mode disclosure ('if the issue hub cannot be read, issues_note says so in the payload'). That is real behavioral context beyond the structured hints, though nothing about pagination or result size.
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 tool's identity, then filters, then the alternative, then a caveat, in five short sentences. Every sentence carries distinct information with no restatement of the name or annotations.
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 does the work of explaining the payload shape at least partially, naming the `issues_note` field and pointing to get_page for full content. It does not enumerate the listed fields themselves (slugs, titles), which is a small residual gap for a discovery 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 coverage is 0%, so the description must carry the parameter burden, and it does: `kind` accepts 'facility' or 'issue' (a constraint the schema lacks entirely, with no enum) and `contains` filters on the slug. It adds genuine meaning beyond the bare string types, though `contains` matching rules (substring vs. exact) remain unspecified.
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 ('List GPS intelligence briefings') and immediately scopes it to two subtypes ('per-facility and per-issue analyses'). It is clearly distinguishable from the read sibling get_page, which it explicitly names as the full-content path.
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 clear when-to-use signal by routing the agent to get_page() for full reads and showing a concrete example path. It lacks explicit exclusions or a 'use this when you only need to discover slugs' statement, so it stops just 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.
Find GPS Historical Data series and dated rule changes by words, e.g. "homicide", "parole", "life", "AIDS", "population", "90%".
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds nothing behavioral beyond the safety profile — no note on how matching works (substring vs fuzzy), case sensitivity, result limits, or empty-result handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the tool's function before the examples. The example list is somewhat long but earns its place by illustrating the kind of input expected.
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 search tool with no output schema, the annotations cover safety and the description covers intent. What's missing is return-shape context (what a hit looks like, result count behavior) and any routing guidance among the many sibling search/list tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% with one required parameter (q) that has no documented meaning in the schema. The description partially compensates by giving example query strings ("homicide", "parole", "90%"), which hints at multi-word/free-text matching, though it never states the search semantics directly.
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 verb ("Find") and resource ("GPS Historical Data series and dated rule changes"), and even gives example query terms. However, several siblings (list_historical_series, get_historical_series, get_historical_events) operate in the same territory, and the description never clarifies whether this is keyword search, listing, or retrieval — the agent must infer it from the name alone.
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 statement of when to use this tool versus the many sibling retrieval tools (get_historical_series, list_historical_series, get_historical_events, search_quotes). The example terms imply free-text search, but no explicit context, prerequisites, or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search GPS's published quote collection — statements from incarcerated people, families, officials and staff that GPS has already published.
`attribution_type` is 'named' or 'anonymous'. `category` is one of the
published categories (call with no arguments and read the results, or see
gps.press). Paginated: page starts at 1, per_page caps at 100.| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| search | No | ||
| category | No | ||
| per_page | No | ||
| attribution_type | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds useful behavioral details beyond the annotations: attribution_type accepts 'named' or 'anonymous', categories are discoverable via an empty call, and pagination starts at page 1 with per_page capped at 100. This is concrete and non-redundant.
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 well-structured: scope first, then parameter semantics, then pagination. Every sentence adds useful information with 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?
The tool has no output schema and five parameters, and while category discovery and pagination are addressed, the 'search' parameter's behavior and the result format are left unspecified. Still, the description provides enough to make a safe first call and explore the collection.
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 0%, so the description must compensate for the schema's lack of parameter documentation. It explains attribution_type, category discovery, and page/per_page bounds, but it leaves the 'search' parameter semantically undefined—what it matches and how it behaves is not stated.
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 states a specific verb and resource: 'Search GPS's published quote collection', and clarifies the content scope as statements from incarcerated people, families, officials and staff that GPS has already published. This clearly distinguishes it from sibling data-retrieval tools and search_site.
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 conveys the intended use case—searching already-published quotes—and gives helpful operational guidance such as calling with no arguments to discover categories. However, it does not explicitly contrast this tool with search_site or other siblings, so when-not-to-use is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search gps.press — articles, data pages, research library topics and facility pages — and get back ranked titles, URLs and summaries.
This reads the public /find/ results page. GPS publishes no JSON search API, so results are parsed out of the rendered page; treat the ranking as the site's own and follow each result's URL before citing it.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations by disclosing that the tool parses the public /find/ results page because GPS publishes no JSON search API, that ranking reflects the site's own ordering, and that citations should be verified by following result URLs. This gives the agent important behavioral context not encoded in readOnlyHint, idempotentHint, or destructiveHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The first sentence front-loads the action, scope, and return type. The second sentence adds essential behavioral caveats about the scraping mechanism and citation workflow. Every clause 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 description covers the tool's purpose, source, output format, and a critical behavioral caveat (parsed HTML, no API). It lacks explicit explanation of the 'limit' parameter and does not mention error or edge-case behavior, but for a simple 2-parameter search tool with rich output and behavioral context, it is largely 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?
With 0% schema description coverage, the description carries the burden for explaining parameters. It implies 'query' is the search term through the verb 'Search', but it never explains the 'limit' parameter, its default behavior, or any constraints. The parameter names are self-explanatory to a degree, but the description adds almost no explicit semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Search'), a concrete resource ('gps.press'), the scope of content ('articles, data pages, research library topics and facility pages'), and the output ('ranked titles, URLs and summaries'). It clearly distinguishes itself from sibling tools like search_quotes by focusing on site-wide search rather than a dedicated quotes search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when the tool is appropriate: when you need to search the public gps.press site across multiple content types. It also implies a caveat for using results (follow each result's URL before citing). It does not explicitly name alternative tools or state when not to use it, but the domain scope is implicit enough for an agent to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_facebook_postsget_contraband_incidents1 field changedInput schema / properties / per_page / defaultPrevious value: -25New value: +5get_historical_series2 fields changedInput schema / properties / limitAdded value: +{
+ "default": 25,
+ "title": "Limit",
+ "type": "integer"
+}Input schema / properties / offsetAdded value: +{
+ "default": 0,
+ "title": "Offset",
+ "type": "integer"
+}get_length_of_stay2 fields changedInput schema / properties / limitAdded value: +{
+ "default": 30,
+ "title": "Limit",
+ "type": "integer"
+}Input schema / properties / offsetAdded value: +{
+ "default": 0,
+ "title": "Offset",
+ "type": "integer"
+}get_parole_statistics5 fields changedInput schema / properties / from_yearAdded value: +{
+ "default": 0,
+ "title": "From Year",
+ "type": "integer"
+}Input schema / properties / limitAdded value: +{
+ "default": 100,
+ "title": "Limit",
+ "type": "integer"
+}Input schema / properties / metricAdded value: +{
+ "default": "",
+ "title": "Metric",
+ "type": "string"
+}Input schema / properties / offsetAdded value: +{
+ "default": 0,
+ "title": "Offset",
+ "type": "integer"
+}Input schema / properties / to_yearAdded value: +{
+ "default": 0,
+ "title": "To Year",
+ "type": "integer"
+}list_facilities2 fields changedInput schema / properties / limitAdded value: +{
+ "default": 25,
+ "title": "Limit",
+ "type": "integer"
+}Input schema / properties / offsetAdded value: +{
+ "default": 0,
+ "title": "Offset",
+ "type": "integer"
+}get_historical_eventsget_historical_serieslist_historical_seriessearch_historical_dataget_contraband_incidentsget_contraband_summaryget_drug_admissionsget_facilityget_facility_staff_rosterget_gps_guideget_length_of_stayget_mortality_dataget_ocga_sectionget_pageget_parole_statisticsget_population_snapshotget_settlements_dataget_system_statisticslist_facilitieslist_intelligencesearch_quotessearch_siteGeorgia's Code, bills, and Supreme Court opinions as source text. Independent, not the State.
Georgia education, Census, and immigration data: query, filter, aggregate, and link datasets.
Keyless, read-only US public records for agents: SEC, FDA, enforcement, sanctions, market data.
Read-only PDGA disc golf data — players, events, courses and season statistics.
Add one secure layer between your agents and this server.
