What Do They Know?

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds 'prefilled,' indicating the URL embeds query parameters, and 'request URL' implies no side effects beyond returning a string. This gives extra behavioral context beyond 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 a single, compact sentence that communicates the core function without wasted words. It is front-loaded with the action and object, making it easy to scan.

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 5 parameters and no parameter documentation or usage guidance, the tool is under-specified. The output schema exists but doesn't help the agent understand how to construct the URL or what each parameter does. This is a significant gap for a tool with multiple optional parameters.

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 lists 5 parameters with 0% description coverage, and the description does not explain any of them. The agent is left to infer the meaning of authority_slug, body, tags, title, and default_letter solely from their names, which is insufficient for reliable invocation.

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 the specific verb 'Build' and clearly identifies the resource as a 'prefilled WhatDoTheyKnow request URL.' This distinguishes it from siblings like create_request_record, which creates a record, and get_* tools that retrieve data.

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 explicit guidance on when to use this tool versus alternatives. The description implies it's for generating a URL link, but it doesn't mention the alternative of create_request_record for record creation or specify scenarios like 'when you need to share a pre-filled form link.' The usage context is only implied.

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 provide openWorldHint and destructiveHint. The description adds the requirement for WDTK_API_KEY and the experimental API status, which is useful additional context. However, it does not disclose further behavioral details such as side effects, idempotency, or error handling, leaving some gaps beyond what annotations already cover.

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 short sentences that immediately state the operation and a key prerequisite. It is front-loaded, free of redundancy, and each sentence contributes meaningful information without unnecessary elaboration.

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 four required, undocumented parameters and an experimental write API, this description is too sparse. It omits parameter meanings, the domain concept of 'request', and any guidance on how the destructiveHint annotation applies. Even with an output schema, the input side remains largely unexplained, making it hard 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?

The schema has four required parameters with zero description coverage, and the tool description does not mention any of them. The description fails to compensate for the schema's lack of detail, forcing the agent to infer meaning solely from parameter names like 'title', 'body', 'external_user_name', and 'external_url'.

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 'Create a request' with a specific verb and resource, and it distinguishes from siblings like update_request_state and get_request_detail by being the only create operation. The mention of 'experimental write API' further clarifies it is a write action.

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 implies the tool is for creating requests and notes the need for WDTK_API_KEY and the experimental nature, which gives some usage context. However, it does not explicitly state when to use this tool versus alternatives, nor does it provide any exclusions or alternative tool references.

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. The description adds valuable context by specifying the returned content (contact/profile fields, tags, publication links, statistics) and by noting 'where WhatDoTheyKnow exposes them,' which aligns with the open-world hint. It does not discuss errors or rate limits, but this is not critical for a read-only getter.

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, each serving a distinct purpose: statement of behavior, summary of returned data, and usage note. There is no repetition or filler, and the structure front-loads the core purpose.

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 one-parameter, read-only tool with an output schema and strong annotations, the description is complete. It covers the return contents, the important slug format nuance, and provides a fallback lookup path. The output schema already handles return-value details, so no further exposition is necessary.

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 no description for authority_slug (0% coverage), but the description compensates with a clear format rule: underscores not hyphens, a concrete example ('home_office' not 'home-office'), and a pointer to search_authorities for finding valid slugs. This adds meaningful guidance beyond the raw 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 begins with a clear, specific verb+resource combination: 'Return full public JSON for a WhatDoTheyKnow public authority.' It distinguishes this from siblings by stating it covers authority data, and the closing reference to search_authorities further clarifies 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 description explicitly directs users to 'Use search_authorities to find the correct slug,' providing an alternative for a specific prerequisite. However, it does not fully contrast when to choose get_authority_detail over other sibling detail tools like get_request_detail, though the resource difference is implicit.

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?

With no annotations, the description bears the full burden of behavioral disclosure. It reveals that the tool returns a rendered prompt as JSON with a messages array, and that arguments must be a dict mapping names to values. While it does not cover error conditions or permissions, the read-only nature is implied by 'Get' and the output description, providing useful 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 three short sentences, leading with the primary action, then the return type, then argument formatting. Every sentence adds necessary information with no redundancy or filler, making it highly concise and well-structured.

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 simplicity, the presence of an output schema, and the two well-documented parameters, the description covers the essential aspects: what it does, what it returns, and how to provide arguments. It omits edge-case behavior but is adequate for a straightforward getter 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?

The input schema already documents both parameters with 100% coverage, so a baseline of 3 is warranted. The description adds value by specifying that arguments should be a dict and by clarifying the role of the name parameter, reinforcing and slightly expanding on 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 uses the specific verb 'Get' with a clear resource ('a prompt by name') and mentions optional arguments, distinguishing it from the sibling tool 'list_prompts'. It clearly states the action of retrieving a single rendered prompt, leaving no ambiguity about what the 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?

The implied usage is straightforward: use this tool to retrieve a specific prompt by name with optional arguments. However, it does not explicitly mention alternatives or when not to use it, such as when a list of prompts is needed instead. The guidance is minimal but not misleading.

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. The description adds value by specifying what content is returned (metadata, public body, requester details, state, info_request_events) and adding a caveat about 'visible' events and 'where WhatDoTheyKnow exposes it,' which informs the agent about data availability constraints.

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-loads the core action, and provides a useful breakdown of the response structure. No filler or redundant phrases.

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 one simple parameter, strong annotations, and an output schema present, the description is well-positioned. It lists the response contents and includes a caveat about visibility/exposure, which is sufficient for an agent to decide to use the tool. Slightly more detail on error cases would be nice, but it's not necessary given 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 schema has one required parameter request_slug with no description (0% coverage). The tool description does not explain what a request_slug is or how to obtain it. The only implicit hint is 'for a WhatDoTheyKnow FOI request,' which is too weak to compensate for the missing schema description.

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 'Return full public JSON for a WhatDoTheyKnow FOI request,' which is a specific verb and resource. The second sentence enumerates the contents (metadata, public body, requester, state, info_request_events), clearly distinguishing this from sibling tools like get_request_feed_items or create_request_record.

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 implies the tool is for retrieving a single request's full JSON, but does not explicitly state when to use it versus alternatives or provide any exclusions. It gives clear context but no explicit guidance, so it falls at the implied-usage level.

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 safety profile is known. The description adds valuable behavioral context: it returns parsed AtomEntry objects rather than raw XML, and discloses that each entry's `link` field contains the request URL for use with get_request_detail. This goes beyond the annotations without contradicting them.

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 concise: three sentences, each contributing distinct value (purpose, usage alternative, output detail/next step). It is front-loaded with the main purpose and contains 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 the read-only annotations and presence of an output schema, the description covers purpose, usage guidance, output format, and a follow-up action. The only notable gap is the unmentioned `limit` parameter, but since it is optional with a default, the overall context is strong and nearly 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 description coverage is 0%, so the description must compensate. It explains `request_slug` conceptually ('specific FOI request') but completely ignores the `limit` parameter, its default, or its purpose. With only one of two parameters addressed, the description does not sufficiently compensate for the lack of 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 clearly states a specific verb ('Return'), a precise resource ('parsed Atom feed entries for a specific FOI request'), and the output form ('structured objects'). It distinguishes this tool from reading the raw feed resource and from get_request_detail, making the tool's purpose unambiguous.

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

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

It explicitly instructs to use this tool instead of the raw wdtk://requests/{slug}/feed resource when structured AtomEntry objects are needed, and provides a clear follow-up action ('use the slug from that URL with get_request_detail for full detail'). This is explicit when-to-use guidance with a named alternative.

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 establish readOnlyHint, openWorldHint, and idempotentHint, yet the description adds valuable behavioral detail: it converts Atom content to readable text in `content` and mirrors it to `summary`. This explains output behavior beyond what annotations or an output schema might imply, and there is no contradiction with 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 two sentences, with the core purpose front-loaded and no unnecessary words. The contrast with the raw resource is concise and adds meaningful value without padding.

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 simple two-parameter schema and the presence of an output schema, the description covers the essential transformation (Atom to readable text) and the user-specific scope. It lacks some details like pagination or error handling, but the output schema and annotations mitigate those needs. It could be slightly stronger by explicitly distinguishing from get_request_feed_items.

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 has no descriptions for `user_slug` or `limit`, and the description barely addresses them. It indirectly references `user_slug` via 'a user's WhatDoTheyKnow activity' but never explains the `limit` parameter or its default behavior. With 0% schema description coverage, the description fails to compensate, leaving parameter semantics largely unspecified.

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 'Return parsed Atom feed entries for a user's WhatDoTheyKnow activity', clearly identifying the action (return) and resource (user feed entries). It also explicitly contrasts with the raw wdtk://users/{slug}/feed resource, distinguishing it from a simplified version. This uniquely differentiates it from sibling tools like get_request_feed_items.

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 context by contrasting with the raw resource and explaining that this returns structured entries with Atom content converted to readable text. However, it does not explicitly name alternatives like get_request_feed_items or state when to prefer this over them, so it stops short of full when/when-not 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?

Annotations already provide readOnlyHint, openWorldHint, and idempotentHint. The description adds useful behavioral context: it specifies that only visible requests are returned, lists the exact return fields, and explains that status_filter is a case-insensitive substring match. 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?

The description is two short paragraphs: the first states the core purpose, the second lists return fields and the filter behavior. Every sentence earns its place, and the most critical 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 list tool with full annotations and an output schema, this description is complete. It covers the source (public requests page), the scope (visible requests), the returned fields, and the filter semantics. No significant gaps that would impede 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?

With 0% schema description coverage, the description must compensate. It does so for status_filter by explaining its matching behavior. user_slug and limit are self-explanatory from the tool name and standard usage, so the partial explanation is sufficient.

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 clearly identifies the resource: a user's visible WhatDoTheyKnow requests from their public requests page. This distinguishes it from sibling tools like get_request_detail (single request) or get_user_feed_items (feed items), making the tool's purpose unambiguous.

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

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

The description gives clear context: it lists a user's visible/public requests, implying it is for public-facing data. It does not explicitly name alternatives or exclusions, but the context is sufficient for an agent to infer when this tool is appropriate.

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 discloses the return format (JSON with prompt metadata including name, description, and optional arguments), which is useful. However, with no annotations, it does not explicitly state the read-only nature or any additional behavioral constraints beyond the list action.

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 concise, front-loaded with the primary action, and includes only relevant additional information about the return format. Both sentences earn their place without 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?

For a simple list tool with no parameters and an output schema, the description is complete. It clearly states what the tool does and what the response contains. No further details about authentication or side effects are necessary given the read-only nature implied by 'List'.

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 zero parameters, so there are no parameter semantics to cover. Per the rubric, the baseline for 0 parameters is 4, and the description appropriately does not need to add parameter details.

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 'List' with a clear resource 'all available prompts', effectively distinguishing it from sibling tools like get_prompt which retrieves a single prompt. The scope 'all' adds clarity and differentiates this tool's purpose.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not mention get_prompt or any other sibling tool, nor does it suggest a discovery workflow or any exclusions.

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 and idempotentHint, but the description adds critical context: matching logic (name or short_name, case-insensitive), the limit parameter's effect, and the output shape (includes a slug field). 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?

The description is compact, front-loaded with purpose, and includes an example and next-step usage in a clear, structured way. Every sentence adds value.

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 available, the description doesn't need to detail return values. It covers purpose, parameters, behavior, and next steps, making it fully self-contained 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 provides zero description coverage, but the description explains query as the search string and limit as the maximum result count. The example demonstrates the query parameter's usage, fully compensating for the lack of schema 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?

The description states a specific verb ('Search') and resource ('WhatDoTheyKnow public authorities') and defines the search scope ('by name'). It clearly distinguishes from sibling tools like search_request_events and get_authority_detail.

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 explains the behavior (matches name or short_name, case-insensitive, limit parameter) and provides explicit next-step guidance: 'Use the slug field with authority_json or build_request_url as the next step.' The example clarifies 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?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, covering the safety profile. The description adds useful behavior details: returns up to `limit` AtomEntry objects and advises using the `link` field for navigation. This clarifies result structure 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 well-structured: it opens with the primary purpose, immediately gives usage guidance, then provides example expressions. Every sentence adds value with no redundant fluff, making it easy to scan.

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 search tool with a query expression language, the description covers purpose, usage, parameter semantics, and navigation next steps. The output schema handles return value details, and the included examples provide essential syntax that would otherwise require external documentation.

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?

With 0% schema description coverage, the description fully compensates by explaining the limit parameter ('Returns up to `limit` AtomEntry objects') and illustrating the search_expression syntax through multiple examples. Both parameters are effectively documented beyond the raw 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 it searches WhatDoTheyKnow's feed-based event index to find FOI requests matching a query expression, distinguishing it from sibling tools like search_authorities. It even provides example query expressions, making the tool's purpose unmistakably specific.

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 says 'Call this to find FOI requests matching a query expression' and gives guidance on next steps (extract slug, call get_request_detail or get_request_feed_items for full detail). While it doesn't explicitly contrast with search_authorities, the clear usage context and example expressions provide strong guidance for when 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.

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

Annotations already declare destructiveHint and openWorldHint, so the agent knows the tool is potentially destructive and the schema may not be closed. The description adds valuable context by stating that WDTK_API_KEY is required in the server environment and that the API is experimental, which is beyond what annotations convey. This enhances the agent's understanding of operational constraints.

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 purpose, and contains no filler. Every word contributes to clarity, and the structure is easy to parse for an agent.

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 write tool with an output schema and annotations, the description covers the essential operational context: it is experimental, requires an API key, and updates a specific aspect of a request. It does not describe side effects or reversibility, but the annotations already warn of destructiveness, and the output schema handles return values. Overall, it is sufficiently complete for agent use.

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?

With 0% schema description coverage, the description must compensate, and it does partially by clarifying that 'state' refers to 'user-assessed state,' which adds meaning beyond the parameter name. However, it does not enumerate valid state values or explain request_id semantics beyond the obvious name. Given only two parameters, this is sufficient but not exceptional.

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 'Update' and identifies the resource as 'user-assessed state of a request,' which clearly states what the tool does. This distinguishes it from sibling read tools and even from create_request_record, as it focuses on updating an existing request's state rather than creating a new record.

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 implies that this tool is for modifying an existing request's state, but it does not explicitly mention when to use it over alternatives like create_request_record. It also does not provide any exclusions, prerequisites beyond the API key, or comparison to other write tools. The mention of 'experimental write API' gives some context but no direct usage guidance.

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