Click on "Install 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., "@NeedRail show me open needs related to clean water"
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.
NeedRail — Get what you NEED to succeed & do agentic public good.
Agent-native coordination layer for public goods (MCP + x402 + Needs).
NeedRail is funded by donations and sponsorships only. There is no commercial seat or metered search SKU.
Agent rail: x402-cloudflare-starter
Surface | Entry |
MCP (stdio) |
|
CLI |
|
API |
|
SDK |
|
Related MCP server: synai-relay
No API keys required to list or call registry tools.
{
"mcpServers": {
"needrail": {
"command": "python",
"args": ["-m", "needrail.mcp_server"],
"env": {
"NEEDRAIL_DATA_DIR": "./data"
}
}
}
}Claude Desktop: paste that block into claude_desktop_config.json.
Cursor: .cursor/mcp.json. Glama: Deploy the repo Dockerfile (CMD python -m needrail.mcp_server).
pip install -e .
python -m needrail.mcp_serverApache-2.0
Soft-claim an open or funded Need so claimer becomes the worker. Sets claimed_by and status=in_progress. Fails if the Need is not claimable. Does not complete work — call complete_need with evidence_links when done. Side effect: updates needs.json.
| Name | Required | Description | Default |
|---|---|---|---|
| claimer | Yes | Worker agent or human id. | |
| need_id | Yes | Need id to claim. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses the internal state changes (sets claimed_by and status=in_progress), the failure mode, the non-completion boundary, and the side effect on needs.json. This gives an agent a clear model of what to expect.
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 information: purpose, operational effect/failure mode, alternative route, and side effect. It is front-loaded with the verb and resource and contains zero 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?
Given the output schema exists and annotations are absent, the description covers purpose, effect, failure condition, non-completion boundary, recommended follow-up tool, and side effect. An agent has everything needed to decide when to call it and what will happen.
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 already has 100% coverage of both parameters, so the baseline is 3. The description adds minor context by explaining that 'claimer becomes the worker' and that claiming sets status, reinforcing the claimer semantics, but it does not add format details 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 precise verb ('soft-claim'), the target resource ('open or funded Need'), and the effect ('claimer becomes the worker'), while distinguishing itself from complete_need in the same description. This separates it from all sibling tools without requiring schema inspection.
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 tells the agent when to use it (on claimable Needs) and when not to use it to complete work, directing it to complete_need with evidence_links. 'Fails if the Need is not claimable' further establishes the intended precondition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a Need completed and attach comma-separated evidence URLs. Writes a completion Receipt. Destructive to workflow state (status becomes completed) but does not delete the Need row. Prefer claim_need first. evidence_links must be comma-separated URLs or artifact paths the requester can inspect.
| Name | Required | Description | Default |
|---|---|---|---|
| need_id | Yes | Need id to complete. | |
| completer | Yes | Worker id attesting completion. | |
| evidence_links | Yes | Comma-separated evidence URLs or artifact paths. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses the key side effects: a completion Receipt is written, the workflow status becomes 'completed', and the row is not deleted. It also gives a validation constraint on evidence_links. This is strong behavioral disclosure, though it stops short of covering reversibility or idempotency.
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 core action, then side effects, workflow guidance, and parameter format. Minor redundancy exists because 'comma-separated' appears twice and 'completed' is restated as status becoming 'completed', but every sentence still 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?
For a three-parameter mutating tool with an output schema, the description covers the critical call semantics, side effects, and a workflow ordering hint. It leaves out details like idempotency and failure behavior, but the output schema can carry return-value information.
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 input schema already documents all three parameters (100% coverage), so the baseline is 3. The description adds value by constraining evidence_links to comma-separated URLs or artifact paths the requester can inspect, reinforcing the field's format 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 verb ('Mark'), a concrete resource ('a Need'), and the result ('completed') with an explicit side-effect caveat that the row is not deleted. This distinguishes complete_need from related mutating tools like claim_need and record_payment.
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?
'Prefer claim_need first' directly tells the agent the proper preceding step and implies this tool is for the final completion stage. It does not spell out when not to use it, which keeps it 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.
Create a new open Need so an agent can request funding or work. Persists to the file-backed registry. Does not move funds — call fund_need afterwards for the x402 payment requirement, then record_payment after settlement. type must be a NeedType value or it falls back to 'other'. acceptance_criteria is a comma-separated list. Side effect: writes needs.json.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | NeedType value: feature, funding, or other. | other |
| asset | No | Asset ticker. Default USDC. | USDC |
| title | Yes | Short title shown on the board. | |
| network | No | CAIP-2 network id. Default Base eip155:8453. | eip155:8453 |
| requester | Yes | Agent or human id that owns the Need. | |
| project_id | No | Optional parent project id. | |
| description | No | Longer problem statement. | |
| target_amount | No | Decimal string bounty amount. | 10 |
| pay_to_address | No | Receiving wallet. Zero address if omitted. | |
| provenance_source | No | Provenance source label. Default agent. | agent |
| acceptance_criteria | No | Comma-separated acceptance checks. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it delivers: it discloses persistence ('Persists to the file-backed registry'), the concrete side effect ('writes needs.json'), a behavioral boundary ('Does not move funds'), and silent fallback behavior on invalid type values. It stops short of 5 because it doesn't address idempotency, duplicate handling, or failure modes, but the core behavioral profile is transparent.
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 earning its place: purpose, workflow sequencing, parameter validation nuance, and side-effect disclosure. Core purpose is front-loaded, no filler, and the length is proportionate to an 11-parameter creation tool with zero 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?
For a creation tool with an output schema (so return values need no explanation) and no annotations, the description covers the essential ground: what it creates, where it persists, what it does not do, and which sibling to call next. It could optionally mention the broader lifecycle (claim_need, complete_need) or failure conditions, but nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3 and the schema already documents all 11 parameters. The description adds one genuinely new semantic detail — that an invalid type falls back to 'other' rather than erroring — but the acceptance_criteria comma-separated note largely duplicates the schema. Net added value is marginal, so 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?
The description opens with a specific verb+resource pair ('Create a new open Need') and states the purpose ('so an agent can request funding or work'). It clearly distinguishes create_need from its lifecycle siblings by explicitly noting it 'Does not move funds' and naming fund_need as the follow-up, so an agent can tell creation apart from funding, settlement, claiming, and completion 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?
The description gives an explicit workflow sequence: 'call fund_need afterwards for the x402 payment requirement, then record_payment after settlement.' This tells the agent exactly when to use this tool and what to call next, and implies when not to use it (when funds need to move). This is exemplary routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return x402-style payment requirements for an existing Need. Read-only quote: does not mark the Need funded and does not broadcast a transaction. After the payer settles, call record_payment with tx_hash. Missing ids return an error.
| Name | Required | Description | Default |
|---|---|---|---|
| need_id | Yes | Need id to quote payment requirements for. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and it delivers: it discloses that the tool is read-only, has no side effects (does not mark funded or broadcast), and returns an error for missing ids. These are exactly the behavioral traits an agent needs to know before calling.
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 carry distinct value: purpose, side-effect disclosure, and downstream workflow/error behavior. The description is appropriately sized with 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 single-parameter quote tool with an output schema, the description covers purpose, safety profile, error handling, and the next step in the payment flow. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the only parameter, need_id, is fully explained in the schema. The description adds no new parameter semantics beyond the schema, so it meets the baseline of 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?
The description states a specific action ('Return x402-style payment requirements') on a specific resource ('an existing Need'), and immediately distinguishes itself from the settlement step by naming record_payment. This clearly separates it from siblings without needing to inspect schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit context: this is a read-only quote, not the action that funds the Need, and instructs to call record_payment with tx_hash after settlement. This tells the agent when to use this tool versus the alternative in the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one Need by id plus its provenance receipts. Use after list_needs when you need acceptance criteria, pay_to wallets, and history. Returns an error object if missing. Read-only. To change state use fund_need, record_payment, claim_need, or complete_need.
| Name | Required | Description | Default |
|---|---|---|---|
| need_id | Yes | Need id from list_needs or create_need. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the operation is read-only and that an error object is returned if the Need is missing, plus it lists the kind of data returned. This is solid coverage for a simple read tool, though it does not discuss auth or rate limits.
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 sentences, each earning its place: what it returns, when to use it, and which sibling tools handle state changes. The key facts are 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?
The tool has one well-documented parameter and an output schema, so the description does not need to explain return shapes in detail. It covers purpose, usage timing, missing-object behavior, read-only nature, and alternatives, making it complete 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?
Schema description coverage is 100%, so the schema already fully documents need_id as coming from list_needs or create_need. The description adds context about using it after list_needs, but does not add meaningful 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 clearly states a specific verb and resource: 'Get one Need by id plus its provenance receipts.' It also names the key data included (acceptance criteria, pay_to wallets, history), which differentiates it from list_needs and get_receipts without ambiguity.
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 says to use this tool 'after list_needs when you need acceptance criteria, pay_to wallets, and history.' It also names the state-changing alternatives (fund_need, record_payment, claim_need, complete_need), giving clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one project by id, including its currently open Needs. Use after list_projects. Returns an error object if the id is missing. Read-only. For a single Need plus receipts use get_need instead of parsing this payload.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project id returned by list_projects. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It explicitly states 'Read-only' and describes the error behavior when the id is missing, adding useful operational context beyond the property 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?
Four short sentences cover purpose, usage sequence, error behavior, and sibling differentiation with no filler. The key scoping detail is front-loaded in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one well-documented parameter and an output schema, the description covers the essential context: what it returns, when to call it, what happens on missing ids, and which sibling to use instead. Nothing critical is left unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already explains that project_id is 'Project id returned by list_projects.' The description reinforces this with 'Use after list_projects', but does not add substantial new 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 opens with a specific verb and resource: 'Get one project by id', and clarifies the payload includes 'currently open Needs'. It also distinguishes itself from get_need, which retrieves a single Need plus receipts, so an agent can tell siblings apart.
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 explicit sequencing guidance ('Use after list_projects') and states when to prefer get_need instead of parsing this payload. This directly helps an agent choose between this tool and its closest sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List provenance receipts, optionally scoped to a Need or project. Use after record_payment or complete_need to audit payment and completion events. Read-only. Omit both filters to dump the whole ledger.
| Name | Required | Description | Default |
|---|---|---|---|
| need_id | No | Optional Need id scope. | |
| project_id | No | Optional project id scope. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly states 'Read-only' and warns that omitting both filters dumps the whole ledger. It does not mention pagination or authorization, but it provides solid safety and scope behavior for a read-only list tool.
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 three short sentences with no redundancy. It front-loads the action and resource, then adds scope, timing, safety, and default behavior. 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?
For a simple read-only list tool with two optional parameters and an output schema, the description covers invocation timing, scoping semantics, read-only safety, and default filter behavior. It does not need to explain return values because an output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema by stating that the filters are optional, that they scope to a Need or project, and that omitting both changes the query to a full-ledger dump. This helps the agent predict result behavior.
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 verb and resource: 'List provenance receipts.' It also names the scoping dimensions (Need/project) and the audit purpose, which clearly distinguishes this from sibling project/need/payment tools. An agent can tell exactly what this tool does 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 description explicitly tells when to use the tool: 'Use after record_payment or complete_need to audit payment and completion events.' It also explains the behavior when filters are omitted. It does not enumerate negative cases or alternatives, but the workflow context is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Needs with optional filters (status, type, project_id, requester). Use this to browse the board before get_need / claim_need / fund_need. status follows NeedStatus (open, funded, in_progress, completed). type follows NeedType. Read-only; create_need writes a new row.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | NeedType filter such as feature or funding. | |
| status | No | NeedStatus filter such as open or funded. | |
| requester | No | Limit results to one requester id. | |
| project_id | No | Limit results to one project id. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It explicitly declares read-only behavior and enumerates the status values (open, funded, in_progress, completed) plus the NeedType link. It does not mention pagination or ordering, but for a simple read-only list that gap is minor.
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-load the core action and filters, then add usage guidance and a read-only caveat. No filler or redundant restating of the schema beyond useful enum/navigation context.
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 four optional parameters, an output schema, and no annotations; the description covers purpose, filtering, usage timing, and safety in a compact way. It could mention default behavior when no filters are passed or pagination, but it is otherwise complete for agent selection.
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 input schema already provides descriptions for all four parameters, so the baseline is 3. The description restates the filter names but adds some value by specifying possible status values and the NeedType relationship; it does not significantly deepen requester/project_id semantics.
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 verb and resource ('List Needs') and enumerates its optional filters, immediately distinguishing it from singular get_need and write-oriented create_need. It also situates it as the browse tool before claim/fund actions.
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 this to browse the board before get_need / claim_need / fund_need, giving a clear when. The 'Read-only; create_need writes a new row' line provides a when-not condition and names the write alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List NeedRail projects, optionally filtered by exact tag membership. Use this to discover project ids before get_project or list_needs(project_id=...). Read-only file-backed registry. Does not create Needs (create_need) and does not return receipts (get_receipts).
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Optional exact tag to match against project.tags. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although no annotations are provided, the description discloses read-only behavior and describes the registry as file-backed. It also clarifies scope by explicitly ruling out creation and receipts. Slight gap: it does not describe the output shape, but an output schema exists, so this burden is covered elsewhere.
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 sentences with no waste: purpose, usage guidance, and exclusions are all packed in efficiently. The most relevant information 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 read-only, single-optional-parameter listing tool with an output schema, the description covers purpose, placement in the workflow, behavioral traits, and exclusions. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema already documents the tag parameter with an exact match description. The description echoes this as 'exact tag membership' and 'optionally filtered' but adds little 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 NeedRail projects') and clearly differentiates from siblings by naming get_project, list_needs, create_need, and get_receipts. The optional tag filter is included. An agent can readily tell what this tool does.
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 says to use this to discover project ids before get_project or list_needs(project_id=...). It also states what it does not do (create Needs, return receipts), giving clear when-to-use and when-not-to-use direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a payment receipt after on-chain or x402 settlement. Writes a payment Receipt and, if the Need is still open, flips status to funded. Does not verify the tx_hash on-chain in this version — treat as attested by from_entity. Side effects: receipts.json + needs.json. Not a substitute for complete_need.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | No | Amount string. Defaults to the Need target. | |
| need_id | Yes | Need id that received the payment. | |
| tx_hash | Yes | Transaction hash or x402 settlement id. Not verified on-chain. | |
| from_entity | Yes | Payer id attested on the receipt. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral burden. It fully discloses side effects ('receipts.json + needs.json'), the mutation of status to funded, and the critical caveat that tx_hash is not verified on-chain and should be treated as attested by from_entity. This is exemplary transparency.
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 tight sentences: purpose, side effects/status behavior, verification caveat, and relationship to complete_need. Every sentence earns its place and important information is front-loaded with the primary action.
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 there are no annotations, the description covers all essential operational knowledge: what it does, when to use it, what side effects occur, what it does not verify, and what it should not replace. An output schema exists, so return-value documentation is already handled elsewhere. The definition is complete for safe 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?
Schema description coverage is 100%, so the baseline is 3. The description adds useful context about the trust model around tx_hash and from_entity, but the schema already documents these details. No parameter-level meaning beyond the schema is needed, but none is significantly added either.
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 clear verb and object: 'Record a payment receipt after on-chain or x402 settlement.' It then states what is written, the conditional status flip for open Needs, and explicitly differentiates itself from complete_need with 'Not a substitute for complete_need.' An agent can confidently understand what this tool does and how it differs from at least one 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?
The description gives a precise trigger condition: use after on-chain or x402 settlement. It also provides an explicit exclusion by stating it is not a substitute for complete_need. However, it does not address how this relates to the sibling fund_need, so the routing guidance is strong but not fully complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct resource and action: project discovery vs. need browsing vs. state transitions vs. receipt auditing. The descriptions also cross-reference one another to prevent confusion between similar operations like fund_need and record_payment.
All tool names consistently follow a verb_noun snake_case pattern, e.g., list_projects, get_need, create_need, record_payment. There are no mixed conventions or vague generic verbs.
Ten tools is well-scoped for a NeedRail domain covering project lookup, need CRUD basics, funding, payment recording, claiming, completion, and receipts. Each tool covers a meaningful step in the workflow without redundancy.
The core need lifecycle is well covered: create, browse, fund, record payment, claim, complete, and audit receipts. Minor gaps exist, such as no project creation/update, no need editing, and no cancellation or close operation, but agents can complete the primary workflow without dead ends.
Workflow diagnostics, capability routing, and x402 settlement for MCP-compatible agents.
MCP server for Boson Protocol — on-chain agentic commerce for physical & digital goods.
Hosted MCP for Conductor Relay: a verifier-backed agent work exchange and cold marketplace.
Hosted AgentLux MCP server for marketplace, identity, creator, services, and social flows.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ANAMIZED/needrail'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
