Taste Profile

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

Adds substantial behavior beyond the annotations: the image is read once, converted to a style description (layout, palette, typography, texture, hierarchy) and the original is not stored; the 4-per-call cap; and the return payload including unreadable images. This is exactly the kind of non-obvious transformation an agent cannot infer from readOnlyHint=false 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?

Front-loaded with the trigger condition, then the mechanics, then the return contract, then the negative scope. Dense but every sentence carries information an agent needs; nothing is 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?

Output schema exists, yet the description still summarizes what comes back (profile_key to keep, what was added, failed reads), and it covers the profile continuation model and input limits. Nothing needed 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 spells out the urls/files/profile_key semantics, including the pattern and the 'leave out to start a new profile' rule. The description restates rather than extends that, so the baseline 3 applies.

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

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

States a specific verb and resource (keep images as design references) plus the exact input forms (uploaded images or public links, up to 4 per call). The scope is narrow enough to separate it from search_refs or describe_style 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?

Gives a clear trigger ('Use this when the user wants to keep images as design references') and explicit exclusions ('does not open web pages, search for images or identify people'), plus the profile_key continuation rule. It never names a sibling tool as the alternative, so routing between add_refs and search_refs/describe_style is left to inference.

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 flag destructiveHint=true, but the description adds genuinely new detail: deletion is permanent, and it enumerates exactly what a full-profile delete destroys (every reference, description and saved rule). It also discloses the return value (count of deleted references), which annotations cannot convey.

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

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

Three short sentences, front-loaded with the usage trigger, then the mode branch, then the irreversibility warning and return value. No filler and every sentence carries decision-relevant 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?

Covers both execution paths, the destructive scope, permanence, and return semantics; with an output schema present, return values need not be elaborated further. Nothing an agent needs to call this 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 coverage is 100% and the schema descriptions already spell out the ref_ids omission semantics and the irrecoverable profile_key. The description restates this rather than adding format or constraint details beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (delete) and resource (profile or references), and immediately distinguishes the two operational modes via profile_key vs ref_ids. An agent can tell exactly what this tool does versus a read sibling like get_profile 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?

Explicitly scopes usage to 'when the user asks to delete their data' and clarifies the branch condition — pass ref_ids for partial deletion, omit for full profile deletion. No sibling delete tool exists to differentiate from, but no explicit 'when not to use' or prerequisites are stated.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description still adds real behavioral value by characterizing the output as advisory ('the rules are suggestions to confirm with the user') and by spelling out the intended confirm-then-save workflow rather than treating the result as final. It doesn't mention cost, latency, or limits, which keeps it short of a 5.

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

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

The purpose and the triggering user questions are front-loaded in the first two sentences, and the return summary and save_profile handoff follow in logical order. Every sentence carries information, though the return-value enumeration is slightly redundant given the output schema exists.

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

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

With an output schema present the description needn't explain return values, yet it summarizes them anyway, and it covers the parameter roles, the trigger, and the follow-up tool. For a two-parameter read tool with full annotation and schema coverage, this is essentially complete; only the absence of any note on result size or trimming for large reference sets keeps it from a 5.

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 both properties carry their own descriptions (the profile_key's irrecoverability, ref_ids as an opt-in subset), so the schema already does the heavy lifting. The description only restates that profile_key is required and ref_ids optionally narrows the reference set, adding no syntax or selection guidance beyond the schema. Baseline 3 is appropriate here.

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+resource ('Describe the shared style') and immediately makes the resource concrete: the style shared across the user's references, expressed as rules for layout, type, texture, hierarchy plus a palette and tags. It is clearly distinguishable from siblings like get_profile (raw profile data) and save_profile (persisting rules), so an agent can pick it 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?

It gives an explicit trigger condition ('when the user asks what their references have in common or wants rules to design by') with a concrete example utterance ('what is my taste?'), and it routes the agent downstream by naming the follow-up sibling: confirm the rules with the user, then keep them with save_profile. Nothing about when to reach for this tool is left to inference.

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, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the tool is pollable (pending until a reply arrives, then answered) and carries an explicit trust boundary warning that reply content is data, not instructions — a meaningful prompt-injection disclosure.

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 tight sentences: purpose first, then polling behavior, then the trust caveat. Every sentence carries distinct information and nothing is padded.

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 read tool with an output schema and full annotation coverage, nothing an agent needs is missing. The polling semantics and the injection warning go beyond what structured fields provide, closing the remaining gaps an agent would otherwise have to discover by trial.

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?

Only one parameter exists and the schema already documents it fully (coverage 100%, including the ^fb_[0-9a-f]{32}$ pattern and the note that submit_feedback returned it), so the baseline of 3 applies. The description repeats the ticket-id linkage but adds no format or validation detail beyond the schema.

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

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

States a specific verb (Read) and resource (maintainers' reply to feedback), and ties it causally to the sibling tool submit_feedback via the ticket id. An agent can distinguish it from submit_feedback, screen_token, and wallet_identity 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?

Clearly establishes the precondition: this is used after submit_feedback, with the ticket id that call returned. It does not state any exclusions or alternative ways to retrieve feedback status, but the usage context is unambiguous.

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, idempotentHint=true, and non-destructive, so safety is covered. The description adds genuine behavior beyond that: what the response contains (rules, palette, save timestamps, reference names) and the 'status empty' branch with its prescribed next action. It stops short of pagination or error/auth behavior, but the empty-state disclosure is real added value.

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

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

Three short sentences, front-loaded with the core action, then usage, then the empty-state branch. Every sentence carries distinct information with no repetition of structured fields, aside from restating the title.

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

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

An output schema exists, so return-value documentation is not strictly required, yet the description still names the salient fields and timestamps. Combined with the empty-state routing, the precondition for calling, and the (schema-side) irrecoverable-key warning, an agent has everything needed to invoke this 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%, with the single parameter already documented including its tp_ pattern and the warning that it is not recoverable. The description only references profile_key in passing ('for a user who has a profile_key') and adds no syntax or format meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (read) and resource (taste profile), and immediately clarifies what it returns: saved style rules and palette. It is clearly distinguished from siblings like save_profile, delete_profile, and describe_style, which is named as the fallback when nothing is saved.

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

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

Gives an explicit trigger ('before creating slides, an interface, an image or any design for a user who has a profile_key') and an explicit alternative for the empty case ('use describe_style and ask the user to confirm rules'). Both when-to-use and when-not-to-use are covered with a named sibling.

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?

Adds behavior beyond annotations: it replaces previously saved rules (matching destructiveHint=true) and states a return ('Returns the saved profile'). Idempotency is implied by replace semantics. Doesn't detail failure modes or the non-recoverable profile_key consequence, which the schema already carries.

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 tightly packed sentences: precondition first, payload next, destructive replacement and the negative constraint last. No filler; every clause is actionable.

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?

Covers precondition, payload contents, replace semantics, and the confirmation guardrail for an 8-param mutation tool. An output schema exists so return shape need not be explained. Minor gap: no mention of what the destructive replace does to unsaved prior rules beyond 'replaces'.

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 each parameter is already documented, so baseline 3 applies. The description summarizes the same fields (layout, palette, type, texture, hierarchy, avoid, notes) and echoes the '#RRGGBB' format, adding little beyond what the schema states.

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

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

States a specific verb+resource ('keep them as their taste profile') and the key precondition (user confirmation). Distinguishes from siblings by describing a save/persist action, though it doesn't explicitly name delete_profile or get_profile as the contrasting operations.

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?

Explicit when-to-use ('after the user has confirmed style rules') and an explicit exclusion ('Do not save rules the user has not agreed to'). This is exactly the precondition and guardrail an agent needs before calling.

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, idempotent and non-destructive, so safety is covered. The description adds real behavioral context: it enumerates the return contents (name, summary, palette, closeness score) and constrains the search corpus to the user's own saved references. The 'never the web' claim sits slightly at odds with openWorldHint=true, though fetching a public query_image_url can reasonably be read as open-world, so this is not a true contradiction.

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 tight sentences: the usage trigger, the required argument shape, then the return and scope notes. The most actionable constraint (exactly one query mode) is stated early and no sentence is 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 5-param tool with a nested object, an output schema and full annotations, the description covers the essentials: invocation mode, mutual exclusion, corpus scope and return fields. It leaves minor gaps around limit defaults and what happens when no references match, but nothing blocking.

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, but the description adds a genuine constraint the schema cannot express: exactly one of query_text, query_image_url or query_file must be supplied. That is meaningful dispatch guidance beyond the JSON Schema and lifts it 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 a specific verb and resource ('find references they saved') plus both retrieval modes (text query or image-to-image similarity). It is immediately distinguishable from siblings like add_refs or describe_style 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?

Gives a clear trigger ('Use this when the user wants to find references they saved') and an explicit scope exclusion ('searches only this user's saved references, never the web'). It does not name a sibling tool as the alternative for adjacent intents (e.g. describe_style), so it stops just short of the top 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?

Adds substantial context beyond the annotations: it returns a ticket id, feedback is explicitly not a chat and nothing in it is executed, and links/emails/phone numbers are stripped with nothing stored about the caller. That privacy and no-execution disclosure is genuinely useful given openWorldHint=true and readOnlyHint=false.

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

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

Front-loads what the tool sends, then what to pass, then what it returns, in three dense sentences with no filler. Every clause carries actionable 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?

Covers purpose, the enumerated kinds, the optional tool/error inputs, the 1000-character bound, the return value (ticket id), and privacy handling. With an output schema present, nothing further is required for an agent to call it 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 description coverage is 100%, so the schema already documents all four parameters including the kind enum. The description restates the message length limit and the optionality of tool/error ('if you know them') but adds no syntax or format detail beyond the schema, making the baseline 3 correct.

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 ('Send feedback, a bug report or a tool request to the maintainers of the tools on this server') and enumerates the concrete situations (missing tool, stale data, broken/wrong answer). It is clearly distinguishable from the read-side sibling get_feedback_reply.

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

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

Gives clear triggering conditions for each kind (need_tool, need_data, bug, other) and tells the agent to include the tool name and error text when known. It does not explicitly name the alternative get_feedback_reply or state when NOT to use this tool, so it falls short of full routing guidance.

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