reliefweb-mcp-server

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses significant behavior: the archive is 'thousands of entries deep', a profile over the response budget returns a section outline with byte sizes, and 'Nothing is truncated on any path.' These are non-obvious behavioral traits that an agent would not infer from annotations alone.

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 sentences long and front-loaded with the primary purpose. Every sentence earns its place: the first states the core function, the second adds authoritative context, and the third explains the selectors and budget behavior without wasted words.

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

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

For a tool with nested objects and selectors, the description is remarkably complete: it covers the archive depth, the mutual exclusivity of sections/archive, the response-budget outline fallback, and guarantees no truncation. Since an output schema exists, return-format details are not needed. This covers all practical aspects an agent would need for invocation.

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

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

The schema already covers all parameters with 100% description coverage, so the baseline is 3. The tool description adds extra meaning beyond the schema, notably the distinction that archive 'pages one list's archived entries in place of the profile' and the outline fallback with byte sizes. While some of this is duplicated in the schema's property descriptions, the synthesis adds value, justifying a 4.

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: 'Fetch a country profile from ReliefWeb by ISO3 code.' It clearly differentiates from sibling get_* tools by focusing on the country profile, and adds unique context about OCHA curation and the archive/sections selectors that are distinct to this tool.

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

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

The description provides clear usage context: 'provide the authoritative situation summary for humanitarian responders' implies when to use this tool. It also clearly explains when to use the archive selector vs. sections ('sections names parts of the profile to return, archive pages one list's archived entries in place of the profile'). However, it never explicitly mentions alternative sibling tools or when not to use the tool, so it falls 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.

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

Annotations already declare readOnly, openWorld, and idempotent hints, so the bar is lower. The description adds substantial non-obvious behavior: archived entries are excluded from the record, a record over the response budget returns a section outline with byte sizes, and 'Nothing is truncated on any path.' It also discloses that description and profile overview can be tens of KB, setting size expectations.

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

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

The description is dense but orderly: purpose, usage context, then behavioral caveats. Every sentence contributes unique information (archive exclusion, response budget, outline behavior, no truncation, mutual exclusivity). It is front-loaded with the core fetch purpose and scales detail appropriately for a complex tool.

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 is complex with nested objects, two modes, and response-budget nuances; the description fully covers these. It explains what happens in normal, archive, and over-budget cases, and since an output schema exists, return-value details are not required. The description is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description enriches this by clarifying the high-level semantics of the two mutually exclusive selectors—'sections names parts of the record to return, archive pages one list's archived entries in place of the record'—and by explaining the outline-spelling behavior that connects to the sections parameter. This goes well beyond repeating schema descriptions.

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-plus-resource statement: 'Fetch a disaster record by ReliefWeb numeric ID including description, affected countries, GLIDE number, profile overview, key content links, and active appeals or response plans.' It clearly distinguishes this from sibling getters by naming the disaster resource and referencing the companion search tool.

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

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

It explicitly instructs 'Use after reliefweb_search_disasters to retrieve full details.' It also explains the two alternative selectors ('sections' vs 'archive') and notes they are mutually exclusive, saying 'at most one per call' and that a call supplying both is rejected. This provides clear when-to-use and alternative guidance.

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

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

The description reveals that the tool reaches expired postings in addition to open ones, and that oversized responses return a section outline with byte sizes rather than being truncated. These behaviors go beyond the annotations' read-only/idempotent hints, adding meaningful operational detail.

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 sentences, front-loaded with the primary purpose, and every sentence provides useful guidance (when to use, expired coverage, oversized response handling). No redundant or filler 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?

Given the output schema and rich parameter descriptions, the description covers the essential behaviors: what is fetched, when to use, and edge-case response handling. It leaves no major gaps for an agent to invoke the tool correctly.

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

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

The input schema already provides thorough descriptions for both parameters, including the self-contained re-fetch behavior for sections. The tool description adds only a high-level restatement of the sections usage ('re-call with sections to pull only the ones needed'), which does not significantly increase semantic clarity beyond what the schema already covers.

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

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

The description clearly states the tool fetches a job posting by numeric ID with a specific list of included content (description, application instructions, dates, hiring organization, location, taxonomy metadata). It distinguishes from siblings like reliefweb_get_report by naming the resource type and explicitly references the search tool it complements.

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 instructs to use after reliefweb_search_jobs, explaining that search results lack the full description and application instructions. It also provides conditional guidance for handling oversized records via a section outline and re-calling with sections, which is clear usage context.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description reveals key behavioral traits: report bodies are 10–100KB, records over the response budget return a section outline with byte sizes, and the self-contained re-fetch semantics. It explicitly states 'Nothing is truncated on either path,' which is valuable behavioral context not present in annotations.

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

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

The description is compact and front-loaded, with the primary action first, followed by the usage context, size warning, and fallback behavior. Every sentence adds necessary information without redundancy or 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 presence of an output schema and complete parameter schema, the description covers the essential aspects: purpose, usage sequence, size constraints, response-budget behavior, and non-truncation guarantee. It is fully adequate for an agent to understand and invoke the tool correctly.

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

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

The input schema already has 100% coverage with detailed descriptions for both id and sections. The description reinforces these meanings and adds the context that section names come from the outline response and that the call is self-contained (re-fetched and sliced). This enhances understanding beyond the schema, though not dramatically.

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 the action explicitly: 'Fetch a single ReliefWeb report by its numeric ID with full body text, file attachments, and all metadata.' It clearly identifies the resource (single report), the verb (fetch), and the scope (full body, attachments, metadata), differentiating it from sibling tools like reliefweb_search_reports which return search results without full bodies.

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

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

The description provides explicit usage guidance: 'Use after reliefweb_search_reports to retrieve document content' and explains why (body is excluded from search results). It also gives a conditional workflow for oversized records, instructing to re-call with specific sections. This clearly distinguishes when to use this tool versus the search tool.

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

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

Annotations already mark readOnly and idempotent; description adds that concluded listings are reachable, that oversized records return a section outline with byte sizes instead of full data, and that nothing is truncated on either path. This goes beyond annotations by explaining response-budget 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?

Four sentences, front-loaded with main action, each sentence adds distinct value: purpose, usage sequence, coverage, and response-budget behavior. No redundant 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?

With output schema present and annotations covering safety, the description covers selection (what it returns), use case (after search), edge case (oversized responses), and non-truncation. Sufficient for an agent to invoke correctly.

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

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

Input schema fully documents both parameters. Description adds context that sections are used after an outline response and that the call is self-contained, but doesn't repeat schema detail; modest added meaning above 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 'Fetch a training listing by ReliefWeb numeric ID' with a specific list of included fields, and explicitly differentiates from reliefweb_search_training by noting search returns summaries without description, registration instructions, or cost detail. Clear verb+resource+scope.

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 instructs to use after reliefweb_search_training and explains what search lacks, establishing a clear sequence. Also gives guidance for handling oversized responses via section re-calls, so when to use sections is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description does not need to restate safety. It adds value by disclosing the return format (ISO3 codes and status) and the behavior of the crisis_only filter. No contradictions with annotations.

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

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

Two sentences: the first gives the primary purpose and return data, the second explains the filter. Every sentence earns its place with zero filler, and the most important 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?

The tool is simple (list with 3 optional params), has a full output schema (noted in context), and the description covers purpose, filtering, and downstream usage. Annotations handle safety, and the schema handles parameter details, so 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?

The input schema has 100% parameter description coverage, so the schema already explains limit, offset, and crisis_only. The description reiterates crisis_only's effect but adds no new parameter details beyond the schema, meeting 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 starts with a specific verb ('List') and resource ('all countries and territories tracked by ReliefWeb'), clearly defining the tool's scope. It also distinguishes itself from siblings by instructing the user to use the returned ISO3 code with reliefweb_get_country for a full profile.

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 explains the optional filtering (crisis_only=true) and how to chain with reliefweb_get_country, implying when to use this tool versus the sibling detail-fetch tool. However, it does not explicitly mention when not to use it or compare with other sibling tools like reliefweb_list_sources, so it falls 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.

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, covering the safety and idempotency profile. The description adds context by stating that it returns short names, types, and URLs, which is not evident from the input schema or annotations. No contradictions found.

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

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

The description is two sentences, front-loaded with the core purpose, and every clause adds value. The first sentence states what the tool does and its filters; the second provides essential usage guidance for downstream tools. No filler or redundant restatement 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?

The tool is relatively simple, has full annotation coverage, 100% parameter description coverage, and an output schema. The description covers the tool's purpose, filters, return contents, and how to integrate with related search tools. Nothing essential is missing for a browsing/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 all parameter meanings are fully documented in the schema. The description mentions 'filtered by name text or organization type' which maps to text and type parameters, but does not add new semantics beyond the schema. The integration note about shortname is cross-tool usage, not parameter syntax.

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 ('Browse') and resource ('source organizations that contribute content to ReliefWeb'), and specifies optional filters. It clearly distinguishes this tool from sibling list/search tools by focusing on source organizations and cross-referencing the search tools that use its output.

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 states when to use this tool: to obtain a shortname for use as a source filter in reliefweb_search_reports, reliefweb_search_jobs, and reliefweb_search_training. While it doesn't cover when not to use it or list alternative tools for browsing other entity types, the integration guidance is concrete and actionable.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints. The description adds meaningful behavior beyond that: the default preset includes alert/ongoing/past, include_archived=true reaches alert-archive entries, and returned IDs are intended as inputs to other ReliefWeb tools. This gives the agent an accurate behavioral model without contradicting annotations.

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

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

Two concise sentences with no fluff. The main action is front-loaded, and the second sentence packs critical usage nuance (archived inclusion and return-value integration). Every word 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?

Given the 11-parameter schema, rich output schema, and strong annotations, the description needs only to orient the agent: it identifies the tool's role, default scope, a key edge case (archived entries), and how outputs connect to sibling tools. This is fully sufficient for an effective agent to select and invoke the tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by summarizing the key filter dimensions ('by type, country, status, date range, and GLIDE number') and by clarifying the default preset (alert, ongoing, past) which is not explicitly stated in the schema's status parameter. The rest of the parameter semantics are already well-documented in 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: 'Search active and historical disasters on ReliefWeb'. It enumerates filter dimensions (type, country, status, date range, GLIDE number) and distinguishes itself from siblings by positioning itself as the search/discovery entry point, with return IDs explicitly linked to reliefweb_get_disaster and reliefweb_search_reports.

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

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

Provides clear context for when to use the archived option ('for historical research') and describes the default preset scope (alert, ongoing, past). It also indicates downstream usage with get_disaster and search_reports, but lacks an explicit 'use X instead of Y' exclusion like the high-calibration example. Still, the guidance is practical and sufficient.

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

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint. The description adds behavioral detail beyond annotations: 'expired postings are excluded by default', the archive is 'far larger than the open set', and include_archived uses 'preset=analysis'. No contradictions with annotations.

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

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

Three sentences with no redundancy. First sentence states purpose, second covers the critical default behavior and how to override it, third gives practical filter guidance. Every sentence 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?

With 10 parameters and an output schema present, the description covers the core purpose, key defaults, and usage guidance. It does not enumerate all filters—leaving that to the schema—but provides enough context for correct invocation. Pagination and limit quota are in the schema, not description, but the description's guidance is sufficient for a search 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 describes all 10 parameters, so baseline 3. Description adds value by explaining the purpose of text search and the semantic difference between open and archived postings, including the 'preset=analysis' detail for include_archived. This goes beyond mere schema property descriptions.

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: 'Search humanitarian job listings on ReliefWeb' and enumerates filter dimensions (country, organization, career category, theme, experience level). It clearly distinguishes from sibling search tools by targeting 'jobs' specifically and notes the default behavior of excluding expired postings.

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

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

Provides clear context for when to use include_archived=true ('to search the full history') and advises using text search for role titles. It lacks explicit mention of when not to use this tool versus sibling search tools, but the resource specialization is sufficient for most cases.

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

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

Annotations already declare read-only and idempotent hints, which the description builds upon by adding behavioral specifics: report body is excluded, results are paginated summaries, every report is reachable by default, include_archived has no effect, and each call counts against the daily quota. No contradiction with annotations.

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

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

The description is compact and front-loaded: it states the primary function first, then usage guidance, a behavioral caveat, and a quota note. Every sentence adds non-redundant value, avoiding verbosity.

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

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

Given the tool's 14 parameters and the presence of a full output schema, the description covers the key usage decisions: when to use it, how to get full content, what happens with include_archived, and the quota impact. No significant gaps remain for an agent to select and invoke the tool correctly.

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

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

The input schema provides 100% parameter descriptions, including the no-effect note for include_archived and default values. The tool description adds little beyond listing filter categories already covered in schema, so it does not enhance parameter understanding 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?

The description starts with a clear verb and resource: 'Search humanitarian reports on ReliefWeb', and enumerates specific filter dimensions (country, disaster, format, etc.). It also distinguishes itself from the sibling tool reliefweb_get_report by noting it returns summaries, not full body text.

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 instructs when to use this tool vs the alternative: 'use reliefweb_get_report to fetch full body text' and 'call get_report when document content is needed.' It also gives context on pagination and the non-effect of include_archived, helping agents decide when not to pass that parameter.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses key behavioral details: training date fields use date.start/date.end (different from report fields), results default to soonest-starting first, and unnamed date bounds scope the search to training starting from now. It also explains how include_archived alters the default date range, all without contradicting the annotations.

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

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

The description is compact and front-loaded: the first sentence states the core purpose, and each subsequent sentence adds a distinct operational detail (date fields, date bounds, default sort, default time scope, archived search). No filler or redundancy.

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 a 12-parameter read-only search tool with an output schema, the description covers all essential usage aspects: searchable facets, coverage (on-site/online), date filtering semantics, default ordering, default time window, and archived listings. An agent has enough context to select and invoke the tool correctly.

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

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

The input schema already covers 100% of the 12 parameters with detailed descriptions, so the baseline is 3. The description adds a useful cross-cutting note about training date fields differing from report date fields and summarizes the default date/archived behavior, but most parameter-level semantics are already in 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 identifies the tool's purpose: searching humanitarian training and learning opportunities on ReliefWeb. It enumerates the filterable dimensions (country, format, date, source, career category, language) and adds that it covers on-site and online capacity-building events, distinguishing it from sibling tools like reliefweb_search_reports or reliefweb_search_jobs.

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

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

Provides explicit guidance on how to use date parameters (date_start_from/date_start_to), explains the default time scoping when no date bounds are supplied, and directs users to include_archived=true for concluded listings. It does not explicitly name alternative sibling tools, but the training-specific focus makes the intended use clear.

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