Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@farmos-mcp show me all active tomato plantings"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server for farmOS 4. It lets an AI assistant look up and record farm data (assets, logs, plans, quantities, taxonomy terms) through farmOS's JSON:API.
It was written against the farmOS 4.0 API changes: assets use the archived boolean instead of a status, plans have planning / active / done / abandoned statuses, and logs can be abandoned. On a farmOS 3 server it falls back to the old status handling for archiving.
Early release (v0.1.0, alpha). Unit-tested against a mock farmOS server, but not yet run against a live farmOS instance. Expect rough edges and possible breaking changes. Try it on a test or demo instance first (see "Verify against your server" below), and do not point write access at production data you can't restore.
Built with AI. This project was written by an AI assistant (Claude, by Anthropic) working with a human maintainer. See AI disclosure.
Tool | What it does | Needs writes |
| Server name/version, current user, available resource types, whether writes are on | |
| Entity types and bundles on this server | |
| Filter / sort / page / include on any one bundle | |
| One record by UUID | |
| Find assets by name across all bundles; active/archived filter | |
| Logs across bundles by status, asset, text, date range | |
| Plans by status / archived / name | |
| Taxonomy terms in a vocabulary (units, categories, plant types...) | |
| Log with locations, categories and quantities in one call | yes |
| Create an asset, log, plan, quantity, term or organization | yes |
| Change fields on a record | yes |
| Archive / restore an asset or plan | yes |
|
| yes |
| Permanently delete a record | yes + delete |
Related MCP server: drupal-mcp
Read-only by default. Writes need FARMOS_ALLOW_WRITES=true. Deletes additionally need FARMOS_ALLOW_DELETE=true.
Writes are limited to asset, log, plan, quantity, taxonomy_term and organization. Users, roles and configuration cannot be written through this server.
Credentials are only sent to the configured FARMOS_URL. Pagination links pointing at another host are refused. Plain http:// is rejected for non-local hosts.
Everything the assistant can do is bounded by the farmOS account it logs in as. Use a dedicated account with the lowest role that does the job (see Roles below).
farmOS 4 made the API and OAuth2 server optional, so check these on your instance:
Enable the API module (farm_api) and the OAuth2 server module (farm_api_oauth) under Administration > Modules (or drush en farm_api farm_api_oauth).
Create OAuth2 keys. farmOS 4 no longer generates them at install. See OAuth2 keys.
Pick an auth method:
Password grant (simplest). Uses the built-in farm client with a farmOS username and password. This is a legacy grant type: it also requires the simple_oauth_password_grant module, and is only appropriate when the MCP server is a trusted first-party client on your own machine.
Client credentials (better for unattended use). Create a client (consumer) in farmOS with a secret and the client credentials grant, mapped to a user. Set FARMOS_CLIENT_ID and FARMOS_CLIENT_SECRET.
farmOS 4 split the default roles into separate modules and changed what they can do:
Viewer: read-only. Right for a read-only deployment.
Worker: can create and edit records, but in v4 can no longer delete other users' records or edit/delete taxonomy terms.
Manager: full records access including terms and deletes.
The OAuth scope must match a role the user has. The default scope here is farm_manager; change FARMOS_SCOPE to farm_worker or farm_viewer for a narrower token.
cd farmos-mcp
python3 -m venv .venv
.venv/bin/pip install -e .Requires Python 3.11+ and mcp 2.x (this project uses the 2.x MCPServer API).
Environment variables (see .env.example):
Variable | Default | Meaning |
| required | Base URL, e.g. |
| Password grant credentials | |
|
| OAuth client id |
| Client secret (client credentials grant) | |
|
| OAuth scope ( |
|
| Token endpoint path |
|
| Enable create/update/archive/status tools |
|
| Enable |
|
| Request timeout, seconds |
|
| Skip TLS verification (not recommended) |
|
| Allow |
If a password is set it wins; otherwise a client secret selects the client credentials grant.
{
"mcpServers": {
"farmos": {
"command": "/absolute/path/to/farmos-mcp/.venv/bin/farmos-mcp",
"env": {
"FARMOS_URL": "https://farm.example.com",
"FARMOS_USERNAME": "claude-assistant",
"FARMOS_PASSWORD": "...",
"FARMOS_SCOPE": "farm_worker",
"FARMOS_ALLOW_WRITES": "false"
}
}
}
}For Claude Code: claude mcp add farmos --env FARMOS_URL=https://farm.example.com --env FARMOS_USERNAME=... --env FARMOS_PASSWORD=... -- /absolute/path/to/farmos-mcp/.venv/bin/farmos-mcp
Do these in order against a test instance (the public demo is a reasonable target for reads):
Ask for farm_info. You should see version 4.x and a list of resource types. A token error here means a setup problem from the section above, not a code problem.
search_assets with no arguments, then list_logs with status: done.
Enable writes on a throwaway instance and try create_log with a quantity.
Parts most worth checking on a real server, because they follow documented behavior but were only exercised against the mock:
boolean filters (archived is sent as 0/1),
quantity value written as {"decimal": "..."},
timestamp filters as epoch seconds, timestamp writes as ISO 8601,
the token endpoint path (/oauth/token, overridable).
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytestTests use httpx.MockTransport, so no farmOS server is needed.
This repository was developed with substantial use of AI:
The code, tests and documentation were written by Claude (Claude Sonnet 5.5, Anthropic) in an interactive session with the maintainer, who directed the work. The design choices, API behavior and docs were drafted by the model from farmOS's public documentation.
The farmOS behavior is based on documentation, not on a live server. The model had no access to a real farmOS instance, so request shapes (filters, quantity values, timestamps, the OAuth token endpoint) follow the published docs and have only been exercised against a mock written alongside the code. The mock encodes the same assumptions as the code, so passing tests do not prove the server matches real farmOS behavior.
Human review is limited. The code has not had a full independent audit. Treat it as you would any unreviewed third-party code: read it before running it, especially before giving it credentials or write access.
Security-relevant choices to check: this server sends your farmOS credentials to the configured URL, can create/modify/delete records when enabled, and is driven by an AI model that can make mistakes. Use a dedicated low-privilege farmOS account (farm_viewer or farm_worker), keep FARMOS_ALLOW_WRITES and FARMOS_ALLOW_DELETE off unless you need them, and keep backups.
Issues and pull requests that fix incorrect farmOS behavior are especially welcome. Please say in your PR if AI tools were used.
Uploading files/images, geometry editing, and data streams.
farmOS add-on modules with custom fields are reachable through query_records / create_record, but have no dedicated tools.
Only the stdio transport. Remote/HTTP hosting would need mcp.run(transport="streamable-http") plus your own authentication in front.
Create a log, optionally with locations, categories and quantities. Quantities are created first and then linked; if the log fails to save, the new quantities are removed again. Requires writes to be enabled.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Log name | |
| notes | No | Free-text notes | |
| assets | No | Assets the log is about | |
| bundle | Yes | Log bundle, e.g. 'activity', 'observation', 'harvest', 'input' | |
| status | No | Log status ('abandoned' needs farmOS 4) | pending |
| locations | No | Location assets (land/structure) | |
| timestamp | No | When it happened/will happen: ISO 8601 or epoch seconds. Default: now (UTC) | |
| categories | No | Log category terms (type 'taxonomy_term--log_category') | |
| quantities | No | Quantities to create and attach | |
| is_movement | No | If true, the log moves its assets to its locations | |
| extra_attributes | No | Any other log attributes, merged in last |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond annotations by disclosing the write ordering (quantities first, then linked) and the rollback behavior if the log save fails, plus the write-enabled precondition. Annotations already cover the safe/non-destructive profile, so this added operational context is the right kind of value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the core action, then the non-obvious quantity workflow, then the precondition. Every sentence carries information an agent needs, with no repetition of schema content.
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 an 11-parameter creation tool with full schema coverage, annotations, and an output schema, the description supplies the important non-schema behavior (ordering, rollback, write prerequisite). It is complete enough to call correctly, with only sibling-routing guidance left implicit.
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 11 parameters thoroughly. The description only echoes the optional locations/categories/quantities concepts and adds no syntax or format detail beyond the schema, which meets the baseline for fully documented schemas.
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 ('Create a log') and immediately scopes what can be attached (locations, categories, quantities). It is clearly distinct from listing/status siblings, though it never explicitly contrasts itself with the generic create_record 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?
Usage is implied by the name and the optional-field list, and the 'Requires writes to be enabled' precondition is useful. However, there is no explicit when-to-use guidance versus create_record or set_log_status, and no stated exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create any record. Prefer create_log for logs with quantities. Requires writes to be enabled. Names are not unique in farmOS, so search first to avoid duplicates.
| Name | Required | Description | Default |
|---|---|---|---|
| bundle | Yes | Bundle, e.g. 'land', 'plant', 'activity', 'plant_type' | |
| attributes | No | Field values, e.g. {'name': 'North Field', 'land_type': 'field'} | |
| entity_type | Yes | One of: asset, log, plan, quantity, taxonomy_term, organization | |
| relationships | No | Relationship name -> {'type': 'asset--land', 'id': '<uuid>'} or a list of those. E.g. {'parent': [{'type': 'asset--land', 'id': '...'}]} |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the write semantics are known. The description still adds real context beyond them: an authorization/enablement prerequisite and the duplicate-creation hazard from non-unique names, which an agent cannot infer from the schema. It stops short of saying what happens on validation failure or partial relationship resolution.
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 with no filler, and the highest-value routing information (prefer create_log) is front-loaded in sentence two. Every sentence carries an actionable constraint.
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 4-parameter, non-idempotent mutation with full schema coverage, full annotations and an output schema, the description supplies the prerequisite, the sibling routing and the duplication hazard. Slightly incomplete only on failure behavior and whether relationship targets must pre-exist.
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% — entity_type enumerates valid values, bundle and attributes carry examples, and relationships documents its shape — so the schema does the heavy lifting. The description adds no parameter-level guidance beyond the general duplication warning, which matches the baseline 3.
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 ('Create any record') and names the sibling it should be preferred over ('Prefer create_log for logs with quantities'), so the agent can distinguish it. The word 'record' stays generic — the actual entity types live in the schema — keeping it just 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?
Gives an explicit alternative and the condition that selects it ('Prefer create_log for logs with quantities'), a pre-call workflow rule ('search first to avoid duplicates' because names are not unique), and a hard prerequisite ('Requires writes to be enabled'). When-to-use, when-not-to-use and alternatives are all covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a record. This cannot be undone and may leave other records with dangling references. For assets and plans, set_archived is almost always what is wanted. Requires FARMOS_ALLOW_DELETE=true; confirm with the user first.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Record UUID | |
| bundle | Yes | Bundle of the record | |
| entity_type | Yes | One of: asset, log, plan, quantity, taxonomy_term, organization |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, but the description adds value beyond them: irreversibility ('This cannot be undone'), the side effect of dangling references on other records, an environment-variable gate, and a human-confirmation requirement. None of that is inferable from the annotations or schema, and nothing contradicts the idempotentHint/destructiveHint profile.
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, each carrying distinct loadable information: effect, irreversibility/risk, alternative, and gate/confirmation. The most important constraint (permanence) is front-loaded and there is 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?
For a destructive three-parameter mutation with full annotation coverage and an output schema, the description supplies exactly the missing risk, prerequisite, and alternative information an agent needs before calling. No relevant gap remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so entity_type, bundle, and id are already documented, and the enum-like entity list lives in the schema. The description only alludes to entity types indirectly via the assets/plans alternative, which is marginal added meaning. 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 effect ('Permanently delete a record') and immediately distinguishes itself from the destructive-adjacent sibling set_archived by naming it. An agent can tell this apart from update_record or set_archived 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?
Explicitly routes the agent to the alternative ('For assets and plans, set_archived is almost always what is wanted') and states the prerequisite condition (FARMOS_ALLOW_DELETE=true) plus a required procedural step (confirm with the user first). Both when-to-use and when-not-to-use are covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the farmOS server name, version, the authenticated user, which resource types exist, and whether this MCP server currently allows writes and deletes. Call this first when unsure what the instance supports.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare this as read-only and closed-world, and the description adds meaningful context: it reports the authenticated user and whether writes/deletes are currently allowed. It does not discuss auth requirements or rate limits, but for a simple introspection tool the behavioral disclosure is strong.
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 efficient sentences with the return contents front-loaded and the usage instruction immediately after. Every sentence 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?
With no parameters, a rich output schema, and annotations covering safety, the description supplies everything an agent needs: what is returned and when to call it. Return value structure can be left to the output schema.
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 parameter semantics are inherently minimal. The schema is empty and the description appropriately does not invent parameter guidance.
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, "Show," and lists the concrete server fields returned: name, version, authenticated user, resource types, and write/delete permission status. It is clear, but it does not explicitly differentiate itself from the sibling tool list_resource_types, which also relates to resource types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear usage cue: "Call this first when unsure what the instance supports." That is a useful condition for invocation, though it does not name alternatives or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single record by UUID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Record UUID | |
| bundle | Yes | Bundle, e.g. 'plant' | |
| include | No | Relationships to embed, comma-separated | |
| entity_type | Yes | Entity type, e.g. 'asset' |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, and an output schema documents the return shape. The description adds no behavioral context beyond 'by UUID'—no notes on missing-record behavior or required scoping.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with zero waste. It is efficient, though its brevity contributes to some of the gaps above rather than being a pure strength.
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?
Annotations and a full output schema cover safety and return values, and the schema covers parameters. However, for a 4-param tool sitting among many query/list siblings, the description leaves usage routing and required scoping unexplained.
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 all four parameters (id, bundle, entity_type, include) are already documented in the schema. The description only echoes the UUID concept and omits the required entity_type/bundle scoping, so it adds little beyond the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Fetch) and resource (a single record) plus the key identifier (UUID), which distinguishes it from list/query siblings. It doesn't explicitly contrast with query_records or search_assets, so sibling differentiation is left implicit.
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 versus query_records, search_assets, or list_resource_types. The agent must infer that this is the single-record-by-id path from the description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List logs across bundles, newest first by default, filtered by status, asset, text or date range.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | Only logs at or before this time (ISO 8601; naive = UTC) | |
| sort | No | Sort field, '-' for descending | -timestamp |
| limit | No | Maximum logs to return | |
| start | No | Only logs at or after this time (ISO 8601; naive = UTC) | |
| status | No | Filter by log status. 'abandoned' needs farmOS 4 | |
| bundles | No | Log bundles, e.g. ['harvest', 'activity']. Default: all | |
| asset_id | No | Only logs that reference this asset UUID | |
| name_contains | No | Case-insensitive text in the log name |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds the default ordering ('newest first by default'), which is useful context, but says nothing about pagination behavior, total counts, or what 'across bundles' means for scope beyond the schema's bundles parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with the default sort stated early and no redundant restatement of parameters. Every clause maps to a real capability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, and all 8 parameters are documented in the schema. The description covers the principal filter dimensions; only pagination/total-count behavior is left unaddressed, a minor gap for a read-only list 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 each of the 8 parameters (start/end ISO semantics, status enum with farmOS 4 caveat, bundles examples, name_contains case-insensitivity) is already documented. The description only summarizes the filter families at a high level, adding little beyond the schema; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List logs') plus scope ('across bundles') and default ordering. An agent can distinguish it from create_log, set_log_status, and query_records, though the description never names the closest alternative (query_records) explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the filtering capabilities ('filtered by status, asset, text or date range'), but there is no statement of when to prefer this over query_records or get_record, and no 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.
List plans (e.g. crop or grazing plans). Plan types only exist when the matching farmOS modules are installed.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum plans to return | |
| status | No | farmOS 4 plan status | |
| bundles | No | Plan bundles. Default: all (plan types come from add-on modules) | |
| archived | No | false = not archived, true = archived only, null = both | |
| name_contains | No | Case-insensitive text in the plan name |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real value with the module-dependency caveat that explains why results may be empty, but says nothing about ordering, pagination, or result shape (left to the output schema).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero waste, with the core purpose front-loaded and the caveat immediately after. Every sentence carries information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a rich output schema, full annotation coverage, and 100% schema documentation, the only thing the description needs to add is the module-dependency behavior, which it does. Minor gaps remain around pagination/ordering of results, but nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so limit, status, bundles, archived, and name_contains are all documented in the schema itself. The description mentions plan types/add-on modules, which loosely supports the 'bundles' parameter, but adds no syntax or filtering semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List') and resource ('plans') with concrete examples (crop or grazing plans), which cleanly separates it from siblings like list_logs, list_terms, and list_assets. It does not, however, explicitly contrast itself with the generic query_records alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the verb and by the caveat that plan types only exist when the matching farmOS modules are installed, which signals a possible empty result. There is no explicit when-to-use guidance or pointer to query_records for more complex filtering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List entity types and their bundles (e.g. asset: land, plant, animal; log: activity, harvest, ...). Which bundles exist depends on the farmOS modules that are enabled.
| Name | Required | Description | Default |
|---|---|---|---|
| refresh | No | Re-read from the server instead of using the cached list | |
| entity_type | No | Limit to one entity type, e.g. 'asset', 'log', 'plan', 'taxonomy_term' |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral note — that available bundles depend on which farmOS modules are enabled, i.e. results are server-configuration dependent — but says nothing about caching behaviour (left to the schema's refresh param) or the shape/scale of the response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the tool's purpose and followed by the module-dependency caveat. No filler; the only nit is the awkward line break in the example list.
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?
A simple read-only, zero-required-parameter discovery tool with an output schema that documents the return shape and annotations that cover safety. The description adds the one non-obvious caveat (module-dependent bundles), leaving nothing an agent needs missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both optional parameters (refresh, entity_type) fully documented in the schema, so the baseline is 3. The description adds no further semantics about either parameter beyond what the schema already states.
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 entity types and their bundles') and concretizes it with examples ('asset: land, plant, animal; log: activity, harvest'). It doesn't explicitly contrast with the record-listing siblings (list_logs, list_plans, list_terms), but the resource is clearly a schema/metadata enumeration rather than record retrieval, so an agent can separate them.
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 only implied: an agent would infer this is a discovery call for available entity types/bundles before querying records. There is no explicit 'use this when...' statement, no mention of the sibling list_* tools, and no guidance on when the cache/refresh path matters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List taxonomy terms in one vocabulary. Use the returned UUIDs when linking logs and assets to categories, units, seasons and plant types.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Records per page (max 50) | |
| offset | No | Skip this many terms | |
| vocabulary | Yes | Taxonomy vocabulary (bundle), e.g. 'plant_type', 'season', 'log_category', 'unit', 'material_type' | |
| name_contains | No | Case-insensitive text in the term name |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful context that the tool returns UUIDs intended for linking records, but it does not add much beyond that; output schema exists, so return-format detail is not required.
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 tight sentences with no wasted wording. It front-loads the core action and then adds a useful downstream-use note.
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-only list endpoint with full schema coverage, annotations, and an output schema, the description is nearly complete. The only minor gap is that it does not explicitly position the tool against its siblings.
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 all four parameters are already documented with examples and defaults. The description reinforces the required vocabulary concept but does not add parameter-level meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource: 'List taxonomy terms in one vocabulary,' with a clear scope. It does not explicitly distinguish this tool from nearby siblings such as list_resource_types or query_records, so it is clear but not fully sibling-differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence implies usage by saying to use returned UUIDs when linking logs and assets to categories, units, seasons and plant types. However, it does not state when to choose this tool over alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query one bundle of records with filtering, sorting and paging. This is the general read tool; search_assets, list_logs and list_plans cover the common cases.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Comma-separated fields, '-' prefix for descending, e.g. '-timestamp' | |
| limit | No | Records per page (max 50), or the total cap when all_pages is true | |
| bundle | Yes | Bundle, e.g. 'plant' for assets, 'harvest' for logs, 'plant_type' for terms | |
| fields | No | Only return these attributes/relationships | |
| offset | No | Skip this many records (ignored when all_pages is true) | |
| filters | No | Field path -> value (equality), list (IN), or {'operator': '>=', 'value': 123}. Operators: =, <>, >, >=, <, <=, STARTS_WITH, CONTAINS, ENDS_WITH, IN, NOT IN, BETWEEN, NOT BETWEEN, IS NULL, IS NOT NULL. Relationship paths work, e.g. {'asset.id': '<uuid>'}. Log 'timestamp' filters take epoch seconds. | |
| include | No | Relationships to embed, comma-separated, e.g. 'asset,location' | |
| all_pages | No | Follow pagination until 'limit' records are collected | |
| entity_type | Yes | Entity type: asset, log, plan, quantity, taxonomy_term, ... |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds one real behavioral constraint — it queries a single bundle per call — but says nothing about result volume, response shape, or performance characteristics. With annotations carrying the safety profile, this is adequate but thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero waste, with the primary identification front-loaded and the sibling routing immediately after. Appropriately sized for a tool whose schema does the heavy lifting.
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, full parameter documentation and read-only annotations, the description covers the remaining gap — role and routing. It could briefly note the single-entity/bundle constraint more explicitly, but nothing essential to correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the parameters are richly documented in-schema (sort syntax, filter operators, pagination semantics, limit max). The description adds no parameter-level detail beyond what the schema already provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (query) and resource (records) plus the supported operations (filtering, sorting, paging), and explicitly positions itself as the general read tool against named siblings search_assets, list_logs and list_plans. An agent can distinguish it from every sibling without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"This is the general read tool; search_assets, list_logs and list_plans cover the common cases" gives clear routing guidance toward the specialized siblings. It stops short of explicit when-not-to-use conditions, but the fallback/general-case role is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find assets across bundles (land, plants, animals, equipment, structures, ...) by name, optionally restricted to active or archived assets.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum assets to return | |
| query | No | Case-insensitive text to look for in the asset name | |
| bundles | No | Asset bundles to search, e.g. ['plant', 'land']. Default: all | |
| archived | No | false = active assets only, true = archived only, null = both |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that matching is name-based and scoped by bundle/archive state, but says nothing about result ordering, pagination beyond the limit param, or truncation 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?
Two compact clauses with the primary action front-loaded and the optional constraint trailing. Nothing is wasted, though the second clause slightly duplicates what the schema already documents.
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 full schema coverage, an output schema, and read-only annotations, the description only needs to establish intent and scope, which it does. Only a missing note on result ordering or limit behavior keeps it from being fully self-sufficient.
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%, including the case-insensitive semantics of query and the tri-state meaning of archived, so baseline 3 applies. The description restates name matching and archive restriction but contributes no additional parameter detail.
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 ('Find assets across bundles') plus the matching key ('by name'), which is clearer than a bare 'search'. It stops short of naming how it differs from siblings like query_records or get_record, so an agent must infer the boundary.
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 'optionally restricted to active or archived assets' hints at the archive-filtering use case, but there is no explicit when-to-use guidance and no mention of alternatives such as query_records. Usage is implied rather than directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Archive or restore an asset or plan. In farmOS 4 this sets the 'archived' boolean (assets no longer have a status). On farmOS 3 it falls back to the status field. Requires writes to be enabled.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Record UUID | |
| bundle | Yes | Bundle, e.g. 'plant' | |
| archived | No | true to archive (hide), false to restore | |
| entity_type | Yes | 'asset' or 'plan' |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare non-readonly, idempotent, non-destructive. The description adds genuinely new behavior: version-dependent semantics (archived boolean in farmOS 4 vs. status-field fallback in farmOS 3) and a write-permission prerequisite. It stops short of describing what happens to dependents or the response, keeping it at a solid 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action, then the version caveat, then the precondition — a logical ordering with no filler. Three short sentences that each carry 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?
An output schema exists, so return values needn't be explained, and the description covers the permission requirement and version differences that would otherwise trip an agent up. The only thin spot is absence of guidance versus update_record.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and every parameter is described there, including the archived boolean's true/false meaning. The description's version note adds context for the archived field but nothing beyond what the schema already provides per parameter, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb pair ('archive or restore') and the resource scope ('an asset or plan'), so an agent can tell it apart from generic update_record. It doesn't explicitly name the sibling to prefer, but the operation is unmistakable.
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 prerequisite 'Requires writes to be enabled' is useful context, but there's no guidance on when to use this versus update_record or set_log_status, which are its closest siblings. 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.
Mark a log pending, done, or abandoned (never going to happen, kept for history). Requires writes to be enabled.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Log UUID | |
| bundle | Yes | Log bundle, e.g. 'activity' | |
| status | Yes | New status. 'abandoned' needs farmOS 4 |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: the write-enabled prerequisite and the fact that abandoned records are retained for history rather than removed, which explains why the mutation is non-destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the core action front-loaded, followed by the prerequisite. No redundant restatement of the name and nothing 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?
All three required parameters are documented, an output schema exists, and annotations cover the mutation profile; the description supplies the prerequisite and the abandoned-state semantics. Only the lack of explicit sibling routing keeps it from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline would be 3. The description goes further by defining what the 'abandoned' enum value semantically means (never going to happen, retained for history), adding meaning the schema's terse "'abandoned' needs farmOS 4" does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (mark) and resource (a log) plus the exact set of target states: pending, done, abandoned. It is clearly narrower than the sibling update_record, though it never names that sibling to make the distinction explicit.
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?
"Requires writes to be enabled" is a useful precondition, and "kept for history" clarifies the abandoned case. However, there is no guidance on when to use this versus update_record or create_log, and no exclusions or failure conditions beyond the farmOS 4 note in the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update fields on an existing record (PATCH). Only the fields you pass change. Requires writes to be enabled.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Record UUID | |
| bundle | Yes | Bundle of the record | |
| attributes | No | Only the fields to change | |
| entity_type | Yes | One of: asset, log, plan, quantity, taxonomy_term, organization | |
| relationships | No | Relationships to replace (full replacement per relationship). Use null to clear a to-one relationship. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing PATCH partial-mutation semantics and a real precondition ('Requires writes to be enabled'), which annotations cannot express. It does not mention what happens to omitted fields on relationships or any error behavior, keeping it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each earning its place: operation, mutation semantics, precondition. Front-loaded with the verb and resource, no filler or repetition of the tool 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 an output schema present and full schema coverage, return values and parameter detail need not be re-explained. The description covers the key non-obvious behaviors (partial update, writes-enabled requirement); the remaining gap is sibling routing among the many update-adjacent 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 100% and every parameter is documented in the schema, including the enum-like entity_type list and the relationship-clearing note. The description only reinforces the 'attributes' partial-update meaning and adds no new parameter detail, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Update fields on an existing record') and pins down the HTTP semantics with '(PATCH)', which is more precise than the tool name alone. It does not distinguish itself from specialized mutators in the sibling list such as set_archived or set_log_status, so an agent must infer which mutator to prefer.
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 implication is use this to modify existing records, and 'Only the fields you pass change' hints at partial-update use cases. There is no explicit when-to-use/when-not guidance, and no routing against siblings like create_record, delete_record, set_archived, or set_log_status, which overlap in intent.
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.
v0.1.0create_logcreate_recorddelete_recordfarm_infoget_recordlist_logslist_planslist_resource_typeslist_termsquery_recordssearch_assetsset_archivedset_log_statusupdate_recordScored across 14 tools
The tools are highly differentiated by their scope and action. General record operations are distinct from specific asset, log, and plan operations, making selection intuitive.
The majority of tools follow the 'verb_noun' convention (e.g., list_logs, create_record). While there are variations like 'set_archived', these follow a predictable pattern for state modification.
With 14 tools, the set is perfectly scoped. It covers the entire lifecycle and metadata needs of a complex system without being overly granular or sparse.
The set provides solid CRUD and state management coverage for its core entities (records, logs, assets). While highly complete, advanced relational query logic might require chaining multiple tools.
The HubSpot MCP Server acts as a bridge that enables AI assistants and Large Language Models to securely interact with HubSpot CRM data through natural conversation, without requiring users to understand complex API structures. It provides read-only access to standard CRM objects (contacts, companies, deals, tickets, products, invoices, and more) and their associations, secured via OAuth 2.0, allowing AI agents to perform tasks like summarizing deals, fetching company updates, and looking up record changes.
Read-only AI access to HAVN properties, leads, tasks, files, media, and analytics.
Read-only banking and personal finance for AI agents: accounts, transactions, spending, budgets.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
