socrata-mcp-server

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the lack of destructive side effects is covered. The description adds meaningful behavioral context beyond that: the environment requirement (duckdb provider), the session/scoped nature of the data, and the trigger condition tied to canvas spill-over from socrata_query_dataset.

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 lead with the core behavior and outputs, then add the relational context, environment prerequisite, and invocation timing. There is no filler or repetition of schema details that are already present.

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, one-parameter tool with an output schema and strong annotations, the description covers the necessary invocation context: what it lists, when to call it, and the sole parameter's provenance and failure behavior. Nothing critical 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?

Although the schema already describes canvas_id at 100% coverage, the description adds valuable practical semantics: the canvas ID comes from socrata_query_dataset when a result spills, it is required in practice even though the schema marks it optional, and omitting it yields canvas_id_required. This materially helps an agent invoke the tool correctly.

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

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

The description uses a specific verb and resource: it lists registered tables in a DataCanvas session and names the included details (schema, row count, column names). It also positions itself against sibling tools like socrata_dataframe_query and socrata_query_dataset, so an agent can distinguish it from nearby 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 description gives clear contextual guidance: use it after socrata_query_dataset writes a large result set to canvas, and note that it only matters when CANVAS_PROVIDER_TYPE=duckdb is set. It stops short of explicitly saying when not to use it or naming an alternative, but the usage context is strong.

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

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

Despite readOnlyHint and idempotentHint annotations, the description adds real behavioral value: it explains DuckDB's type inference, the numeric-comparison benefit, the CANVAS_PROVIDER_TYPE=duckdb requirement, and the fact that this is a local table query over spilled data. This goes well beyond what annotations communicate.

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

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

Four sentences, each carrying distinct value: purpose, type behavior, environment prerequisite, and schema-discovery pointer. No filler or repeated schema 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 an output schema present and a fully documented input schema, the description covers the essential operational context: what kind of SQL is allowed, how to find table names, the environment prerequisite, and the type-inference behavior. Nothing critical is missing for an agent to invoke this correctly.

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

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

The schema already covers all three parameters at 100% coverage, so the baseline is 3. The description adds meaningful semantic context for the sql parameter by explaining type coercion behavior with concrete examples (year > 2020, amount < 500), which helps an agent write effective queries.

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

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

The description opens with a specific verb and resource: "Run SELECT-only SQL against a DataCanvas table." It also distinguishes itself from socrata_query_dataset by noting the table is populated by that tool, making the query-layer role clear to an agent.

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

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

It gives clear context: use this after socrata_query_dataset has populated a table, use socrata_dataframe_describe to inspect registered tables, and only use it when CANVAS_PROVIDER_TYPE=duckdb is set. It does not explicitly contrast with every sibling alternative, but the workflow guidance is strong.

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

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

While annotations already declare readOnly, openWorld, and idempotent hints, the description adds transparency about the output quality by warning that columnNames are preview-only and lack type information. No side effects or destructive actions are implied, consistent with the readOnlyHint.

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 succinct, starting with the core purpose, then listing the return values, and ending with a crucial caveat about columnNames. It avoids verbosity while conveying essential information in a clear sequence.

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 key aspects: the scope (all portals or one), the output fields (IDs, names, column lists, domains, update timestamps), pagination via offset/limit, sorting via order, and the relationship to socrata_get_dataset. This is sufficient for an agent to decide when and how to invoke the 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?

Every parameter (query, domain, categories, tags, limit, offset, order, only) is described with examples and constraints, such as 'Use updated_at to surface recently-refreshed datasets' and 'Omit to browse without filtering.' The schema provides full coverage, and the description adds semantic context beyond the field 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 states the tool's purpose: to search for datasets across all Socrata portals or a specific one via the domain parameter. It also differentiates from socrata_get_dataset by noting that columnNames are preview-only, making it distinct as a discovery tool.

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 explicit guidance: use socrata_get_dataset to fetch the full typed column schema before writing queries, highlighting the limitation of preview-only columnNames. It also mentions using order=updated_at to surface recently-refreshed datasets, offering concrete usage advice.

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

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

Annotations already mark the operation read-only and idempotent, and the description adds behavioral context: it returns field names, types, descriptions, row count, and licensing, and warns about literal quoting conventions. No contradiction.

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

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

Two sentences with a front-loaded purpose and a focused syntax example; no filler.

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

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

The description covers the call's purpose, prerequisite (dataset_id), result contents, and its role feeding socrata_query_dataset. With an output schema present, return-value details are appropriately left to the schema; it could mention dataframe siblings, but that is not essential.

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

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

Input schema is 100% covered, with dataset_id describing the ID pattern and source and domain documenting its default. The description reinforces the ID-based lookup but does not need to add parameter-level detail beyond the schema.

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

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

Clearly identifies the operation (fetch metadata/schema by ID) and the resource (Socrata dataset), and differentiates from query tools by focusing on schema rather than rows. The references to column types and WHERE syntax make its role unambiguous.

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

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

Explicitly directs agents to call it before socrata_query_dataset and explains why; it also references socrata_find_datasets as the source of dataset_id in the schema. This is strong when-to-use guidance.

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

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

The annotations already declare readOnlyHint and idempotentHint, but the description adds substantial behavioral context: the catalog is a curated list of 40 portals, dataset counts are fetched from the Discovery API and cached for ~24 hours (so they may be stale), and filtering is client-side substring match. These details are valuable for correct invocation and interpretation.

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 terse sentences with no fluff. The first sentence defines the operation, the second provides essential caveats, and the third gives actionable routing guidance. All content is relevant and 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 read-only, parameterless-required list tool with an output schema, this description is complete. It covers the catalog scope, data freshness, filtering behavior, and suggestions for follow-up actions. No additional context is needed for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds the client-side filtering nuance for 'query', but this is marginal beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource: 'List known Socrata-powered government open-data portals' with fields: domain, organization name, and approximate dataset count. It also names the sibling 'socrata_find_datasets' and explains the relationship, distinguishing the tool clearly.

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

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

Gives explicit guidance: 'Use this first when you do not know which portal to target, then pass the domain to socrata_find_datasets.' This tells the agent when to choose this tool over alternatives and what to do next, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds important behavior beyond annotations: returned rows include the assembled SoQL string, all SODA 2.1 row values are strings regardless of column type, and results spill to a DataCanvas table under duckdb conditions. These are critical, non-obvious behaviors that materially affect how an agent interprets and uses results.

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 dense but efficient—about six sentences, each with a distinct job: core purpose, usage mode, return format, data-type caveat, distinct-value example, spill behavior. Information is front-loaded with the most important action and purpose first. No filler or repetition that would dilute the message.

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 complex 11-parameter tool, the description covers the main execution modes, a critical data-type gotcha, an advanced aggregation pattern, and the spill-to-DataCanvas behavior. The output schema already covers return values, so the description does not need to restate them. The only minor omission is error handling or authentication, but annotations and schema make this a non-issue for a read-only query tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by demonstrating how parameters combine into a coherent query strategy, especially the distinct-value example and the quoting rules tied to dataType. Some of this content also appears in the schema, but the description reinforces it in a usage-oriented way that helps an agent compose valid SoQL.

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

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

Description opens with a specific verb+resource: 'Execute a SoQL query against any dataset on any Socrata portal.' It clearly distinguishes itself from siblings like socrata_get_dataset (metadata) and socrata_dataframe_query (dataframe-based) by focusing on raw SoQL execution. The distinction between full-text search and analytical querying further sharpens purpose.

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

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

Provides clear conditions: use `search` for quick full-text lookup, or combine `select/where/group/having/order` for analytical control. References socrata_get_dataset as a prerequisite for checking data types, and gives a concrete pattern for distinct-value enumeration. It does not explicitly state when to prefer sibling alternatives, but the within-tool guidance is strong and actionable.

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