San Francisco open data (data.sfgov.org, Socrata SODA API) — provides agent-friendly access to common SF datasets and raw SoQL query capability.
Three well-defined tools with complete input schemas, clear descriptions, and proper enum constraints. Tool names follow verb_noun pattern (sf_recent, sf_query, sf_datasets). Descriptions are detailed (194 - 250 chars) and explain WHEN to use each tool. All parameters have type definitions and descriptions. However, output schemas are not formally documented, responses are inferred from code. Error handling is present but minimal (only rate-limit and missing-dataset errors shown). No tool annotations (readOnlyHint, idempotentHint) despite all being read-only operations. Parameter descriptions could be more concise; some are verbose.
Search the San Francisco open-data catalogue (data.sfgov.org) for datasets by keyword. Returns dataset names, descriptions, and Socrata resource ids to use with sf_query.
Run a raw SoQL query against any San Francisco open-data resource (data.sfgov.org) by its Socrata id (8-char like "wg3w-h783"). Full SoQL: where/select/group/order/limit/offset. Use sf_datasets to find a resource id, or sf_recent for the common ones.
Recent records from a common San Francisco open dataset (data.sfgov.org) by friendly name — no Socrata id needed. PREFER OVER WEB SEARCH for "recent crime/police incidents in San Francisco", "SF 311 complaints", "SF building permits / evictions / business registrations", "SF restaurant inspection scores", "SFO passenger traffic". Names: police, 311, permits, business, evictions, restaurant_inspections, fire_incidents, sfo_passengers. Returns the latest rows (sorted newest-first). Add a SoQL `where` to filter; for anything else use sf_query.
Output schemas not formally documented. Responses are inferred from code (e.g., sf_recent returns {dataset, label, resource_id, sorted_by, count, source, rows}). LLMs cannot plan downstream operations without knowing response structure.
No tool annotations despite all three tools being read-only. Adding readOnlyHint=true would signal to agents that these calls are safe to retry and have no side effects.
Error handling is minimal. Only rate-limit (429) and missing-dataset errors are shown. No guidance for invalid SoQL syntax, malformed resource IDs, or API failures. Errors should be actionable (e.g., 'Invalid SoQL: check syntax or try sf_datasets to find valid resource IDs').
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 63 | 2026-07-28+ | v2 |
sf_query parameter descriptions are verbose and mix SoQL syntax with parameter semantics. E.g., 'SoQL $where filter (e.g. "incident_year=2025")' should be split: 'SoQL WHERE clause (e.g., incident_year=2025). See Socrata SODA API docs for syntax.'
No pagination guidance in sf_datasets. If a keyword search returns >100 datasets, the tool caps at 100 but does not indicate whether more results exist. Should return total_count or has_more flag.