Muralists Directory

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

Annotations already declare readOnlyHint=true, and the description's 'Retrieve' is consistent with that. The description adds useful behavioral context: it returns the 'full text' of the profile, requires an id from the search tool, and is intended for citation. 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 two concise sentences, front-loading the action and resource, with no redundant information. Every clause 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?

The tool is simple (one parameter, output schema present, annotations provided). The description covers the purpose, workflow dependency (ids from search), and return scope (full text). No significant gaps remain for this complexity level.

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

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

Schema coverage is 100% and the id parameter already has a descriptive comment ('The profile id (slug) returned by search'). The description reinforces the source of the id but does not add new meaning beyond what the schema provides. Baseline of 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 uses a specific verb 'Retrieve' with a clear resource: 'full text of one Muralists.nl directory profile by id' and a stated purpose 'for citation'. It differentiates from the search siblings by focusing on retrieval by id, but does not explicitly distinguish itself from the similarly named sibling 'get_muralist_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 provides clear workflow context by stating 'Ids come from the search tool', implying use after search. It also mentions 'for citation' as a use case. However, it does not explicitly state when not to use the tool or compare with alternatives like 'get_muralist_profile'.

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, so the safe read behavior is known. The description adds context about what fields are returned but does not disclose error cases, pagination, or other behavioral quirks. This is adequate but not extensive.

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 action and content, followed by a usage note. No redundant or filler wording is present.

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

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

For a simple read-only tool with one parameter, an output schema, and accurate annotations, the description provides sufficient information for an agent to select and invoke it correctly. The usage instruction and content enumeration cover the essential context.

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

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

Schema description coverage is 100% with a detailed explanation of the 'id' parameter as the profile slug returned by search_muralists. The tool description itself does not add any parameter-level meaning, so a baseline score of 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 clearly states 'Get the full profile of a specific muralist' and enumerates the profile contents (bio, styles, portfolio, project types, quote process). It also names search_muralists as the predecessor tool, distinguishing it from sibling listing/search tools.

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 'Use after search_muralists to get details on a candidate,' providing a clear workflow. It does not explicitly state when not to use the tool, but the positive guidance is strong enough to rate above a 3.

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 readOnlyHint=true already provided, the description adds useful behavioral context by stating that the tool returns profile URLs and that users should use fetch with a returned id for full profiles. 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 two sentences and front-loads the key purpose and outcome, followed by a practical follow-up instruction. Every sentence earns its place 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?

Given the simple one-parameter tool, the description adequately covers purpose, output type (profile URLs), and next step. The presence of an output schema reduces the need to detail return values, but the ambiguous relationship with the sibling 'search_muralists' keeps it from being fully complete.

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

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

Schema coverage is 100% and includes an example, but the description adds semantic detail by specifying that the query can target name, city, and style. This enriches the meaning of the 'query' parameter beyond the 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 clearly states the tool searches the Muralists.nl directory by free text (name, city, style) and returns matching artists with profile URLs. However, it does not distinguish itself from the sibling tool 'search_muralists', which appears to serve a similar 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?

The description gives clear context for when to use the tool (for free-text searching) and explicitly recommends using 'fetch' to read full profiles, providing a follow-up path. It does not mention any exclusions or alternatives to 'search_muralists', so it falls short of the highest score.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is known. The description adds value beyond annotations by specifying what the tool returns ('matching artists with portfolio highlights and profile URLs') and reinforcing the curated nature of the directory, which is consistent with the openWorldHint. This helps set expectations without contradicting any structured metadata.

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 compact paragraph with three sentences: what it does, what it filters by, and when to use it. No redundant wording, no filler. Every sentence carries useful information and the main action 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?

Given the presence of a full output schema and self-explanatory parameter descriptions, the description sufficiently covers the tool's purpose and typical use case. It does not need to detail return values because the output schema exists. The description is complete enough for an agent to invoke this tool confidently for a Netherlands muralist search.

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 baseline is 3. The description adds meaning by grouping the filters ('city/region, style, and indicative budget range') and providing concrete style examples (abstract, figurative, lettering, photorealistic, geometric). This enhances understanding beyond the raw schema, though the schema already describes each parameter well.

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+resource: 'Search a curated directory of muralists and street artists in the Netherlands.' It clearly distinguishes this from generic search tools by focusing on this specific domain and from profile-retrieval siblings by emphasizing the search/filter behavior. The phrase 'curated directory' also differentiates it from an open web search.

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 'Use this when someone wants to find, hire, or commission a mural artist in the Netherlands,' giving clear when-to-use context. It does not mention alternatives or when not to use it, but the context provided is sufficient for most agents to select this tool appropriately among siblings like 'search' and 'get_muralist_profile'.

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