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

Annotations already indicate non-readOnly and non-destructive write operation. The description adds valuable behavioral context: it changes status from SENT to ACCEPTED, the action is audit-flagged as 'approvedOnBehalf', and it requires confirmed: true. This goes beyond what annotations provide, though it doesn't detail further side effects.

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, well-structured and front-loaded with the purpose. Every sentence adds value: purpose, audit flagging, request for note and confirmation, differentiation from DRAFT quotes. No unnecessary 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?

Given that there is no output schema, the description adequately covers prerequisites (quote must be SENT), required confirmation, and audit note. It doesn't explain the return value or further effects, but the context is sufficient for a state-change tool. Slightly incomplete on side effects but overall strong.

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 parameters are already described. The description adds meaning beyond the schema by explaining the purpose of 'note' (short audit note) and the condition for 'confirmed' (must be true only after explicit customer confirmation). It reinforces the process, which is helpful for correct 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 clearly states the action: 'Mark a SENT quote ACCEPTED on the customer's behalf.' It specifies the verb (mark as accepted), resource (SENT quote), and context (on behalf). It also distinguishes from the sibling tool setell_approve_quote by explicitly noting 'Not for DRAFT quotes (setell_approve_quote first).'

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 when-to-use guidance: 'they said yes by phone, meeting, or email outside the portal.' It also gives when-not-to-use: 'Not for DRAFT quotes' and directs to the appropriate alternative tool. It instructs to ask for an audit note and get an explicit yes before calling with confirmed: true.

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 that the tool is a mutator (creates an Artifact row), aligns with annotations (readOnlyHint=false, destructiveHint=true), and adds behavioral context: the notes are private to the operator, feed the next quote draft, and content must not be summarized away. 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?

Three sentences: core action with examples, storage behavior, usage guidance. Front-loaded and every sentence adds value. No 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?

For a 3-param mutator with no output schema, the description fully covers purpose, behavioral impact, parameter nuances, and context alternatives. No missing information needed for correct invocation.

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

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

Adds meaning beyond schema: jobId suggests finding via setell_find_jobs, label becomes artifact filename, content advises preserving wording. Schema coverage is 100% but description enriches each parameter with practical usage hints.

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 attaches freeform scoping notes to a job, distinguishing it from the sibling 'setell_save_customer_memory' which stores durable customer facts. It uses specific verbs like 'attach' and 'store' and specifies the resource as 'scoping notes to a job'.

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 states 'Use when the operator narrates field notes' and 'Do NOT use for durable facts about a customer relationship (setell_save_customer_memory)', providing clear when-to-use and when-not-to-use with an alternative tool name.

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 key behavioral details beyond annotations: the tool is non-destructive (never overwrites), idempotent (skips already applied), and seeds structure-only templates. It also mentions the return shape.

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, each packed with relevant info: purpose, safety, return value, and usage advice. No 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 simple tool with one parameter and no output schema, the description covers purpose, behavior, return structure, and usage. The annotations fill in the rest. Nothing 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 description adds context by linking the slug parameter to the list tool, helping the agent understand where valid slugs come from. The schema already covers the enum, so the description provides extra guidance.

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's purpose: to apply a Setell-curated trade playbook, referencing the source (setell_list_playbooks) and distinguishing it from listing playbooks.

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 usage after listing playbooks and advises confirming with the operator before applying. It does not explicitly list when not to use, but the context 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 are minimal; description adds: creates job and customer (write effect), queues AI drafting (async), and plan-gated behavior (quota check). These are beyond annotation hints.

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: first covers core action, second handles error. Efficient and 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 single-param mutation without output schema, it covers effects and error. Missing return description, but sufficient for agent selection.

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

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

Single parameter inboundEmailId; schema covers 100% with description. Tool description adds no extra meaning beyond 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 the verb 'Approve', the resource 'pending inbound email', and the specific effects: creates job/customer and queues AI drafting. It distinguishes from sibling like setell_reject_inbound_email.

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: 'from setell_list_inbox' indicates workflow step. Includes error handling for 402 plan_limit, but no explicit alternatives or when-not-to-use.

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?

Discloses that the quote transitions to a 'live SENT version' and that prior versions are 'superseded', adding context beyond annotations. No contradiction with annotations though destructiveHint is false; 'superseded' is not necessarily destructive.

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 with no redundant information. Purpose is front-loaded and 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?

Given no output schema, the description explains the result (becomes live SENT version) and addresses prior versions. Also clarifies what it does not do, making the tool's behavior fully understood.

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 100% schema coverage, baseline is 3. The description adds value by explaining the confirmation workflow ('State the quote and total, get an explicit yes, then call with confirmed: true'), which is not 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?

Clearly states the verb 'Approve' and the resource 'DRAFT quote', explains the effect ('becomes the live SENT version; prior versions are superseded'), and distinguishes from siblings like setell_send_quote.

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

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

Explicitly tells when not to use ('Does NOT email the customer') and provides alternative tools ('use setell_compose_quote + setell_send_quote for delivery'). Also gives a step-by-step workflow for calling the 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 provide idempotentHint and destructiveHint. The description adds value by explaining the no-op behavior, return value (previous schedule time or null), and the atomic claim with cron. No contradictions.

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 concise sentences with no wasted words. Front-loaded with the main action, then return value, then no-op and cron details. Efficient.

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 tool with good annotations and no output schema, the description covers purpose, behavior, return value, and edge case (no-op). Could mention potential errors or prerequisites, but sufficient.

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% for the single parameter. The description adds 'latest quote' and 'pending schedule cleared', providing slightly more context than the schema, but not significant additional meaning. Baseline 3 is appropriate.

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

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

The description clearly states it cancels a pending scheduled send on the latest quote of a job. It uses specific verb 'clear' and resource 'scheduled send', and distinguishes from sibling tools like setell_schedule_send and setell_send_quote.

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 that it is a no-op if no schedule is pending, indicating safe idempotent use. It does not explicitly state when to use vs alternatives, but the context is clear: use to cancel a scheduled send. Could be improved by mentioning alternatives like rescheduling.

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 goes beyond the annotations by detailing the token's binding to the quote version and recipient, its single-use and expiration properties, and the plan-gated quota impact. It also implicitly indicates mutation (composing is a write) consistent with readOnlyHint=false, and there is no 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?

The description is concise (5 sentences) and front-loaded with the main action. It efficiently lists return fields, provides workflow guidance, and includes crucial behavioral constraints without redundancy. Every sentence serves a 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?

Given the tool's complexity (token-based workflow, quota, binding constraints) and the absence of an output schema, the description covers all necessary context: returns, token lifecycle, approval requirement, and plan-gating. The agent has enough information to use the tool correctly and understand its effects.

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% coverage, but the description adds significant context beyond the schema descriptions. For 'tone', it explains that the brand voice comes from UserSettings and tone controls cadence. For 'recipientEmail', it warns that a mismatch with 'setell_send_quote' invalidates the token. For 'customInstructions', it clarifies the 1000-char limit as a one-paragraph instruction.

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 dual purpose: drafting an AI-generated quote email in the operator's brand voice and minting a single-use confirmation token bound to the specific quote version and recipient. It lists the return fields and is easily distinguishable from its sibling 'setell_send_quote', which uses the token to send.

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 workflow instructions: narrate the preview to the operator, obtain their approval, then call 'setell_send_quote' with the provided token verbatim. It also specifies when not to reuse the token, stating that any revision or recipient change requires re-composing, and notes the token's 15-minute expiration and single-use nature.

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 give idempotentHint=true; description reinforces that a job gets only one invoice and is safe to retry, adding error return types and actionable fixes. No contradiction, and adds value beyond annotations with error 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?

The description is a single dense paragraph that efficiently covers purpose, usage, retry safety, and errors. It is front-loaded with the core action and maintains focus, though slightly packed.

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 no output schema, the description covers key constraints (one invoice per job, accounting preference), error types, and preconditions. Missing success return value description but adequate for confident 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?

Schema descriptions cover both parameters (jobId and confirmed) with 100% coverage. The description adds conversational flow: mention job and amount, then set confirmed=true only after explicit confirmation, which is helpful context not in 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 the tool creates an invoice for accepted/signed jobs, specifies which accounting systems (QuickBooks over Xero), and distinguishes from sibling tools like setell_mark_paid_offline by focusing on creating rather than marking paid.

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

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

Explicitly tells the agent to first state job and amount, get explicit yes, then call with confirmed: true. It also notes safety to retry and lists expected error types with handling instructions, ensuring proper 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?

The description declares the tool as read-only, aligning with annotations. It adds that each match returns jobCount, lifetimeValue, and lastJobAt, providing helpful behavioral detail beyond annotations. No contradictions.

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 concise sentences: first defines purpose and search types, second lists return fields, third states requirements. No unnecessary words, well 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 search tool with 3 parameters and no output schema, the description fully covers return fields, input requirements, and behavior. The information is sufficient for an agent to use 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?

With 100% schema description coverage, the description still adds value by stating the requirement that at least one of email or name must be provided, and that limit defaults to 10. These constraints are not in the schema, so the description significantly enhances parameter understanding.

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 Setell customers by email (exact) or name (partial), lists return fields, and distinguishes from siblings like setell_find_jobs which 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?

The description specifies that at least one of email or name is required, giving clear usage conditions. It does not, however, explicitly mention when not to use this tool or suggest alternatives, but the context of sibling tools implies it is the primary customer search.

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 indicate readOnlyHint=true and destructiveHint=false, so the agent knows it's safe. The description adds that results are limited to 50 rows and sorted by most-recently-updated, providing useful behavioral context beyond 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 front-load the purpose and include usage guidance and behavioral notes. Every sentence adds value with no 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 tool with no output schema, the description covers the key aspects: filtering criteria, result limit, and ordering. It could mention the return format, but the given information is sufficient for an agent to use 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% with each parameter described. The description adds that results are ordered by recency, but does not provide new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'List Setell jobs' with specific filtering criteria, distinguishing it from sibling tools that focus on individual jobs or actions. The verb-resource combination is explicit and matches the title.

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 guidance on when to use this tool ('find jobs by criteria') and when to use the alternative setell://jobs/{id} resource. This is clear and helpful for the agent.

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 indicate readOnlyHint=false and destructiveHint=false. The description adds context: it stores options as a group, does not modify the active quote, and is plan-gated. This provides useful behavioral insight 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 compact with no filler. Core purpose is front-loaded, followed by tier definitions, behavioral notes, and follow-up guidance. 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?

Covers key aspects: tier definitions, storage, non-modification guarantee, quota, and edge case. Lacks details on output format or what 'stores as a group' entails, but overall sufficient for an agent to use 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 sole parameter jobId is described in detail: its current quote becomes the BETTER tier, and we provide lookup hints via setell_find_jobs or the setell://jobs resource. This adds meaning beyond the schema's basic 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 generates three quote tiers (good/better/best) around a job's current quote, with each tier defined. It distinguishes from sibling tools like setell_get_quote and setell_select_quote_tier by specifying its unique role.

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 states when to use (generating tier options), what it does not do (does not change active quote), and what to do next (call setell_select_quote_tier). Also mentions plan-gated usage and the 'no_quote' edge case.

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 adds significant detail beyond annotations: explains the safety floor (FLAG always asks), mode behaviors in different scenarios, and that 'canConfigure' depends on paid plan. This is valuable context beyond the readOnlyHint annotation.

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 paragraph that is front-loaded and informative. Every sentence adds value, though it could be slightly more structured (e.g., bullet points for modes). It is appropriately concise for the complexity.

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 no output schema, the description adequately explains what is returned (modes per action class and canConfigure). It covers the key behavioral aspects, though the exact JSON structure is not provided.

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?

There are no parameters, so the baseline is 4. The description correctly focuses on the return values and behavior, fulfilling the need without parameter documentation.

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 shows per-action-class autonomy modes, specifying the action class 'send_quote' and explaining each mode (WATCH, TRUST, AUTO) along with the 'canConfigure' flag. This provides a specific verb+resource and distinguishes from siblings like setell_set_autonomy.

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?

Usage is implied as a read-only getter for checking current autonomy modes before potentially using setell_set_autonomy. However, no explicit when-to-use or when-not-to-use guidance is provided, nor are alternatives mentioned beyond the sibling 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?

The description reveals that data is sampled over 'SIGNED quotes only', which is a crucial behavioral trait beyond the readOnlyHint annotation. It also describes the row structure and the presence of a customer-wide row. This provides significant context about what the tool returns and its derivation.

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 at four sentences, front-loading the main action and then detailing the output. Every sentence adds value without redundancy. It is well-structured and easy to parse.

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 and no output schema, the description is complete. It explains what is returned, the data source (signed quotes), and provides practical use cases. No additional context seems 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?

Schema coverage is 100%, so the baseline is 3. The parameter `customerId` is already well-described in the schema with guidance on how to find it. The tool description adds overall context but no additional parameter-specific details beyond the schema.

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

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

The description clearly states the tool reads the operator's learned pricing baseline for a specific customer. It specifies the output structure (rows per jobType scope plus customer-wide row) and fields (median, min, max, sampleSize, lastSignedAt). This distinguishes it from sibling tools like setell_get_customer_memory by focusing on pricing 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?

The description provides explicit use cases ('what did I charge Cooper last time?' / 'how many signed quotes does this customer have?'), giving clear guidance on when to use this tool. However, it does not explicitly mention when not to use it or alternative tools for other tasks, though the sibling list implies alternatives exist.

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 destructiveHint=false, so the agent knows it's safe. The description adds value by confirming it's read-only and describing the return shape (memory id, type, content, etc.). No contradictions.

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 long, front-loads the purpose and payload, and ends with a clear read-only note. Every word earns its place—no fluff 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?

For a simple list operation with one parameter and good annotations, this description covers purpose, return shape, and relationship to sibling. It doesn't mention pagination or result limits, but given the simplicity, it's 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 has 100% coverage with a description for customerId. The description goes beyond by clarifying that the customerId can be found via setell_find_customer or the setell://customers resource, which adds meaningful usage guidance.

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 lists CustomerMemory rows for a specific customer, with a concrete verb ('List') and resource ('CustomerMemory row'). It distinguishes from siblings like setell_save_customer_memory by its read-only nature and mentions the auditing use case.

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 context: useful for 'what do I know about this customer?' and as a prerequisite before calling setell_save_customer_memory. It references a direct sibling, but does not list alternative tools for different scenarios, though the context is 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=true, destructiveHint=false, and openWorldHint=false, so the tool's safety profile is covered. The description adds context about its diagnostic role and what it returns, but behavioral transparency is already well-handled by 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, front-loaded with purpose. Every word carries weight—no redundancy or filler. Highly concise and 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 zero parameters, lacking an output schema, and annotations covering safety, the description fully explains the tool's return values and usage context. It is complete for a simple health-check 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 tool has zero parameters, so the schema needs no explanation. The description does not need to add parameter meaning, and the baseline for zero-parameter tools is 4. No additional parameter info is required.

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 checks Setell connection status and lists specific return values (userId, plan tier, Gmail/QuickBooks connections). It is a specific verb+resource, distinctly different from all sibling 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?

Explicitly advises calling this tool first if any other Setell tool fails, to isolate auth/plan problems from data-shape problems. This provides clear when-to-use guidance and distinguishes it from alternatives.

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 key behaviors beyond annotations: the specific calculation method (revenue from payments, cost from price-book or labor rates), the conditional withholding of marginPct when data is insufficient, and the instruction to present UNKNOWN lines honestly. It also emphasizes the operator-only nature, adding value beyond the readOnlyHint.

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?

Every sentence contributes essential information: purpose, calculation logic, null handling, and confidentiality. The description is concise without redundancy, front-loading the core purpose and progressively detailing edge cases and warnings.

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 lack of an output schema, the description adequately explains the key output behavior (marginPct may be null, lines may be UNKNOWN) and the calculation sources. However, it does not specify the exact output fields or structure, which could be clarified.

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 sole parameter jobId is documented in the schema with description. The tool description adds value by advising to find the job via setell_find_jobs or the setell://jobs resource, providing practical guidance beyond the schema.

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

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

The description clearly states the tool computes realized job margin, specifying that it uses revenue from payments and cost from price-book provenance. It distinguishes the tool by emphasizing 'realized margin' and operator-only data, making the 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 does not explicitly guide when to use this tool versus its siblings (e.g., setell_get_margin_summary). It only provides usage-related warnings about not sharing data with customers but lacks when-to-use or when-not-to-use guidance.

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

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

The description adds value beyond annotations by explaining the exact nature of the returned data (e.g., what 'maturityTier' means, the specific fields). It confirms read-only behavior and provides context that annotations alone do not, such as what 'signed quotes' and 'baseline' represent.

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, moderately long paragraph. It front-loads the purpose with a question and then lists the return fields. While efficient, it could be slightly more concise by removing the example usage in parentheses, but overall it is 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?

Despite lacking an output schema, the description fully explains the return structure, including specific field names and meanings. It also provides usage context and examples, making it complete for agent understanding.

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 tool has no parameters, and schema coverage is 100%. Per guidelines, baseline is 4 for zero parameters. The description 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 clearly states the tool returns aggregate counts and a maturity tier summarizing the operator's data depth. It uses a specific verb ('get') and resource ('learning coverage'), and distinguishes itself from siblings by focusing on coverage metrics rather than individual entities or actions.

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

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

The description explicitly advises using this tool when the operator asks 'how much does Setell know about my pricing?' or when narrating analyst verdicts. While it does not provide explicit exclusions or alternatives, the given usage scenarios are clear and helpful.

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 destructiveHint=false. The description reinforces with 'Read-only' and adds operator-only data scope, but does not disclose additional behavioral traits beyond what annotations provide.

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-loading the key output items and then providing usage context and constraints. Every word adds value; no superfluous 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 no output schema, the description compensates by listing what the summary includes (overall margin, per-jobType averages, worst 3 jobs, count below target, uncostable jobs). However, it could further describe output format or structure for full completeness.

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 description for the only parameter 'limit'. The tool description does not add any additional meaning for the parameter, so 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 the tool returns 'realized margin across the operator's recent WON jobs' and lists specific data points (revenue-weighted overall margin, per-jobType averages, worst jobs, count below target, uncostable jobs). It also provides example use cases, distinguishing it from siblings like setell_get_job_margin.

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 gives usage context: 'Use for 'how are my margins?' or monthly profitability check-ins.' It also notes 'OPERATOR-ONLY data.' However, it does not explicitly state when not to use or provide alternative tools.

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 destructiveHint=false. The description adds the behavioral detail that data is raw counts and not prose, which is valuable beyond annotations. No contradictions.

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: the first lists all relevant data points, the second provides guidance on how to use the data. No wasted words, front-loaded with key 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?

Given no parameters and a clear purpose, the description adequately covers what the tool returns and how to interpret it. It could mention data format or limitations, but for a morning brief tool, it is sufficiently 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?

There are no parameters, so schema coverage is 100% and the description provides additional context about the output content, which meets the baseline expectation.

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 'snapshot' and lists the exact data points (new inbound jobs, quotes awaiting review, etc.), clearly distinguishing it from sibling tools that handle individual operations like composing quotes or finding 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?

The description states the data is 'raw counts, not prose' and explicitly says 'Read-only', which provides context for when to use it. However, it does not explicitly mention when not to use it or direct to alternatives, though the context from the sibling list makes it 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 provide readOnlyHint=true and destructiveHint=false, and the description reinforces 'Read-only.' It also adds critical behavioral context: caveats about survivorship, censoring, and small sample sizes that must be repeated when summarizing. This goes beyond the annotations to disclose data limitations and interpretation requirements.

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 dense paragraph that efficiently packs a lot of information (metrics list, usage guidance, caveats). It is front-loaded with the core question but could benefit from clearer structure (e.g., bullet points for metrics). Still, no 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?

Despite having no output schema, the description adequately explains what the tool returns by listing the computed fields and their meanings (pointAccuracy, bandCalibration, etc.) and noting caveats. It covers the single optional parameter (via schema) and usage context. Minor gap: the response structure (object keys, nesting) is not described, but the metrics list is sufficient for an AI agent.

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% for the single optional parameter (horizonDays). The tool description does not mention this parameter at all, so it adds no additional meaning beyond what the schema already provides. 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 the tool's purpose: to evaluate how right Setell's pricing memory has been by joining draft-time price predictions to real outcomes. It lists specific computed metrics (pointAccuracy, bandCalibration, etc.) and differentiates from siblings like setell_get_pricing_signal and setell_get_margin_summary by focusing on calibration, not raw signals or margins.

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 provides usage guidance: 'Use when the operator asks 'is my pricing right?', 'how accurate is Setell's memory?', or 'do I lose work when I price high?'. While it doesn't name alternatives or when not to use, the specificity of these questions makes it clear when to invoke 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 readOnlyHint=true and destructiveHint=false. Description adds that it evaluates the latest quote version, falls back to industry benchmark, and details return fields like priceResponse with FORMING status. 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?

Front-loaded with the key action and purpose. A bit lengthy with return field descriptions, but each sentence adds value. Could be slightly tighter, but structure is effective.

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?

No output schema provided, but description lists and explains return fields (verdict, reasoning, recommendedAmount, comparables, layer, priceResponse). This compensates well. For a read-only tool with one parameter, it is complete enough.

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 has 100% coverage with a description for jobId. Description adds context on finding jobId via setell_find_jobs and clarifies it evaluates the latest quote. This adds value beyond the schema 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?

Description uses a specific verb ('Get') and resource ('pricing signal verdict') and clearly distinguishes from siblings like setell_get_quote by specifying it's a pre-send evaluation. The context signals list 25 sibling tools, and this description uniquely positions the tool as a pricing analyst check.

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

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

Explicitly says 'Use this before send_quote-style actions' and advises on what to do with verdicts: FLAG warrants confirmation, WARN is autonomy-mode-dependent. Does not explicitly mention when not to use or alternatives, but given the sibling list, the usage context 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 provide readOnlyHint=true and destructiveHint=false. The description adds value by detailing the return fields (line items, total, version, status, timestamps), confirming read-only behavior without 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?

Two sentences, front-loaded with the main action, no fluff. Every sentence contributes useful information.

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

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

Given a simple single-parameter tool with annotations and no output schema, the description provides all necessary context: what it returns, how to obtain the id, and its read-only nature. 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 description for quoteId is sufficient ('The quote id (UUID). Required.'). The description reinforces its purpose but does not add new semantic detail beyond the schema, which has 100% coverage.

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 'Fetch a single Setell quote by id' and lists the returned fields. It distinguishes from sibling tools like setell_find_jobs by specifying when to use it once the id is known.

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

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

Explicitly says 'Use this once you know the quote id — get one from setell_find_jobs or the setell://jobs/{id} resource.' Also declares 'Read-only,' guiding against misuse.

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 destructiveHint. The description adds that it is read-only and explains the meaning of baseIsCurrent false, as well as the ordering (most recent first). This adds context beyond 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 with zero waste. The main action is front-loaded, and additional detail is provided efficiently.

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 output schema, the description covers what is returned (label, summary, line items, total, baseIsCurrent) and the ordering. No gaps.

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 parameter jobId has full schema coverage. The description adds value by suggesting how to find the jobId (via setell_find_jobs or setell://jobs resource), which is not in the schema's 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?

Description clearly states the verb 'List' and the resource 'quote tiers for a job', and specifies the details like 'most recent first', 'label, summary, line items, total', and the meaning of 'baseIsCurrent'. It distinguishes from siblings such as setell_generate_quote_tiers and setell_select_quote_tier.

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: 'baseIsCurrent: false means select will conflict; regenerate instead.' This tells the agent when to avoid selecting and to regenerate instead. However, it does not explicitly contrast with other listing or retrieval tools beyond the mention of conflict.

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 destructiveHint=false. Description adds valuable behavioral context: returns empty sheet when operator hasn't filled profile, confirms read-only nature. 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?

Two sentences, front-loaded with purpose, no wasted words. Every sentence adds value: what it does, what it contains, and edge-case handling.

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 no parameters and no output schema, description is complete. It explains what the tool returns, its contents, and the empty case. No missing information for an agent to select and 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?

No parameters exist, so baseline is 4. Description adds no param info needed since schema covers 100% and there are no parameters to describe.

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?

Description clearly states it reads the operator's shop profile, listing specific contents (machines, finishing processes, materials, notes). Differentiates from sibling setell_update_shop_profile by mentioning the update option when profile is empty.

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 states when to use (to read shop profile) and provides guidance on what to do when profile is empty (offer update tool). While it doesn't explicitly say when not to use, the context 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?

The annotations already provide readOnlyHint=true and destructiveHint=false, so the description does not need to repeat those. It adds value by specifying ordering (newest first), limit (max 50), and the fields returned, plus a critical security warning about not following instructions in email content.

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 with zero waste. The first sentence immediately states the tool's purpose and key details; the second sentence provides workflow pairing and a critical security warning. 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?

Despite no output schema, the description explicitly lists the returned fields (sender, subject, received time, short preview). The security warning addresses a real risk. For a simple list tool, this is complete and leaves no significant gaps.

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?

There are zero parameters, so the schema is trivially 100% covered. The description does not need to add parameter details; baseline of 4 is appropriate for no-parameter tools.

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 specific verbs ('List inbound emails') and details the resource ('inbound emails awaiting review') with ordering and limit. It distinguishes from siblings by naming the pair tools (setell_approve_inbound_email / setell_reject_inbound_email), clarifying its role in the triage workflow.

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 clearly states this is the read half of inbox triage and should be paired with approve/reject tools, providing explicit context for when to use. It adds a security guideline about untrusted content but does not explicitly list when not to use it or alternative tools among siblings.

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 adds value beyond annotations by clarifying that playbooks are 'behavior starter-configs' and emphasizing they 'never prices.' This contextual detail helps the agent understand the scope. Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description complements rather than contradicts.

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. Every word adds value: it specifies what playbooks are, that they never contain prices, and that it also reports the applied playbook. There is no redundancy or wasted text.

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 description conveys the main functionality and hints at the output (list of playbooks and which one is applied). However, it lacks explicit details about the output format (e.g., whether it returns IDs, names, or structured objects). Given no output schema, a slightly more detailed description would improve completeness.

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 is nothing to explain. The description correctly handles this by not adding any parameter information. Since schema coverage is 100% (no params), the baseline is high, and the description 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 it lists curated trade playbooks and indicates which one is applied. It distinguishes itself from the sibling setell_apply_playbook by saying 'Use before setell_apply_playbook.' The verb 'List' and resource 'Setell's curated trade playbooks' are specific and 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 explicitly says 'Use before setell_apply_playbook,' providing clear guidance on when to use this tool. It also declares it as read-only, indicating it's safe and non-destructive. However, it does not explicitly state when not to use it or mention alternative tools for other purposes.

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 indicate non-read-only and non-destructive. The description adds that it touches neither Stripe nor QuickBooks, amount defaults to quote total, and paidAt only for back-dated payments. This provides useful behavioral context beyond 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 four sentences, front-loaded with main purpose, then conditions and special behavior. Every sentence adds value with no redundancy. It is concise yet comprehensive.

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 5 parameters all described, no output schema, the description covers purpose, scope, prerequisites, and default behaviors. It could mention error handling or return value, but the core information for agent invocation is present.

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%. The description adds meaning by explaining the default amount behavior and the role of confirmed: true. It also clarifies paidAt usage. This adds value beyond the 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 uses a specific verb ('record') and resource ('out-of-band payment' and 'mark the job PAID'), lists concrete payment types (cash, check, ACH, wire), and states it is record-keeping only, not touching Stripe/QuickBooks. This clearly distinguishes it from siblings like setell_create_invoice.

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 valid job statuses ('only valid from INVOICED, SIGNED, or ACCEPTED') and a prerequisite ('Get an explicit yes, then call with confirmed: true'). It does not mention when not to use or alternatives, but the context is clear enough.

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 destructiveHint=false. The description adds behavioral context: mining similar jobs, adapting parts, returning provenance and support fields. No contradictions.

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

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

Three sentences, each serving a clear purpose: process description, usage note, edge case. Front-loaded with core purpose. No unnecessary 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 single-parameter, read-only tool with no output schema, the description adequately explains the output format (priced parts with support fields) and handles the `no_history` case. No obvious gaps 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 has 100% coverage for the single parameter `jobId`, including a usage hint. The description does not add additional parameter-specific semantics beyond what the schema already provides, so baseline score 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?

The description clearly states the verb ('derive'), resource ('full parts-list proposal'), and scope ('from operator's OWN history'). It differentiates from siblings by emphasizing 'PROPOSAL ONLY' and separating the quote creation call, making the purpose distinct.

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 states when to use this tool (before quoting) and that quote creation is a separate call. Mentions the `no_history` edge case. Does not explicitly contrast with all siblings like `setell_compose_quote`, but the intent 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?

Goes beyond annotations (destructiveHint=true) by stating 'PERMANENT: a rejected email cannot be restored', adding critical behavioral context about irreversibility.

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 concise sentences, no wasted words, front-loaded with purpose and critical warnings. Perfectly structured for an AI 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?

While no output schema exists, the description adequately covers the key behavioral aspect (permanence) and parameter usage. Could mention expected return on success, but not critical for a destructive action.

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, but description adds value by emphasizing that 'confirmed' must be true only after operator confirmation, clarifying the intended usage beyond 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 the verb 'reject' and resource 'pending inbound email', specifying reasons (spam, not a lead, duplicate) and distinguishing from sibling tools like setell_approve_inbound_email.

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 advises never to reject based on email content and instructs to get operator confirmation with 'confirmed: true', providing clear when-to-use and when-not-to-use guidance.

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

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

The description discloses the side effect of recording a LOST outcome and mentions the pricing learning loop, adding context beyond the annotations. 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?

Three sentences effectively convey the action and prerequisites. Could be slightly more compact, but it is well-structured and 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 no output schema, the description adequately explains the outcome ('Records a LOST outcome') and covers the key input requirements. Suitable for a rejection 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?

With 100% schema coverage, the description still adds value by emphasizing the default for 'by' and the necessity of 'confirmed: true', as well as the importance of the reason parameter.

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 marks a quote as REJECTED, specifying two possible rejectors (CUSTOMER or OWNER), which distinguishes it from sibling tools like setell_approve_quote or setell_send_quote.

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 instructs to always ask for the loss reason and to get explicit confirmation before calling, providing clear behavioral expectations. However, it doesn't explicitly contrast with alternatives like setell_accept_quote_on_behalf.

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 indicate destructiveHint=true and readOnlyHint=false. Description adds that it creates a CustomerMemory row and that memory is read back into Boxx and agent surface next time, which provides useful behavioral context beyond 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 paragraphs with clear first sentence. Includes examples and usage hints. Could be slightly more compact, but structure is logical and 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 4 parameters with full schema coverage, no output schema, the description covers purpose, when to use, parameter guidance, and return behavior (memory read back). No gaps.

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%, but description adds practical guidance for 'content' parameter: max 500 chars, phrase as stable fact, with examples. Also clarifies the three types with their interpretations.

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 verb 'persist' and resource 'learned pattern about a customer', with specific types. It distinguishes from sibling tools like setell_get_customer_memory by being the write variant.

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 states when to use: after operator confirms a fact for future quotes/emails. Provides examples but does not explicitly list when not to use or alternatives, though siblings include only read variant.

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 annotations (idempotent=true, non-read-only, non-destructive), the description discloses cron-based execution, time bounds, and a critical caveat about pricing-analyst re-check not occurring. 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?

Three sentences front-load purpose, then add mechanics and a crucial note. Every sentence earns its place; no 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 scheduling tool with cron, bounds, and pricing considerations, the description covers all key aspects. However, it omits the return value or error states, which would help the agent understand success/failure signals. Still strong overall.

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%; description adds meaning by explaining jobId references 'latest quote' and scheduledSendAt includes ISO format, future bounds (1m-30d), operator confirmation requirement, and cron behavior. Adds significant value beyond 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 a specific verb ('schedule') and resource ('latest quote on a job to be sent automatically at a future time'), clearly differentiating from sibling tools like setell_cancel_scheduled_send and setell_send_quote. It also adds implementation detail (cron tick) for clarity.

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 guidance on when to first call setell_get_pricing_signal and mentions the cancellation alternative. However, it does not explicitly contrast with immediate send (setell_send_quote) or state when not to use this tool, though the name implies future orientation.

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 adds significant behavioral detail beyond the annotations (all false). It explains that GOOD/BEST create new quote versions via a deterministic revision engine, while BETTER is a no-op. It also warns about a 409 stale error condition. 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 concise (4 sentences) and front-loaded with the purpose. Every sentence provides essential information: action, level distinction, error handling, and subsequent steps. No 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?

Given no output schema, the description adequately explains the side effects (new quote version for GOOD/BEST, no-op for BETTER) and subsequent steps (compose/send). However, it does not describe the return value, which may be inferred but is not explicit.

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%, but the description adds value by specifying that tierGroupId comes from 'setell_generate_quote_tiers' or 'setell_get_quote_tiers' and explains the semantic difference among the level enum values (GOOD/BEST vs BETTER).

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's purpose: to make a chosen tier (good/better/best) the active quote for a job. It distinguishes between the behavior for GOOD/BEST (creating a new quote version) and BETTER (no-op), which differentiates this tool from siblings like 'setell_generate_quote_tiers' and 'setell_get_quote_tiers'.

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: it is used after generating tiers, and it indicates that compose/send operate on the chosen tier afterward. It also gives error handling guidance (409 stale means regenerate). However, it does not explicitly state when not to use this tool or list alternatives.

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?

Discloses irreversibility (aligns with destructiveHint=true), the pricing-analyst pre-check behavior (409 response), and the atomic guard conditions. Adds context beyond annotations by explaining the pushback response structure and the safety floor, without 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?

The description is dense with information but could be better structured (e.g., bullet points for steps). However, every sentence adds value, and the most critical info (irreversibility, token requirement) is front-loaded. Slightly verbose but acceptable.

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 no output schema, the description thoroughly covers the 409 response format, retry mechanism, and guard conditions. It conveys the full workflow context including operator responsibility and statefulness. Complex tool, high completeness.

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%, but description adds critical constraints like recipientEmail must match compose call, confirmationToken has 15-minute TTL and is bound to a specific version, and acknowledgePricingWarning requires a prior pushback verdict. This significantly enhances parameter understanding.

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 'IRREVERSIBLY sends the doorbell email to the customer' with specific verb and resource. It distinguishes from sibling tools like setell_compose_quote by highlighting the dependency on a confirmation token and from setell_schedule_send by being an immediate send.

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 states when to use: after obtaining a valid confirmationToken from setell_compose_quote. Provides detailed retry logic for pricing pushback, requiring operator confirmation before setting acknowledgePricingWarning. Mentions conditions where the guard rejects (revision, recipient drift, expired token, cross-tenant replay), guiding when not to call.

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 rich behavioral details beyond annotations: explains how each mode handles WARN and FLAG verdicts, mentions atomic correctness guards, and emphasizes operator confirmation. Annotations (idempotentHint=true) are not contradicted and the description adds 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?

The description is a single, well-structured paragraph with no wasted words. It front-loads the purpose, then explains modes, exceptions, guards, and a usage note. Each sentence contributes essential 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?

Given the tool's complexity (three modes, effects, requirements, guards) and absence of output schema, the description fully covers what the agent needs to know: mode behavior, prerequisites, and a critical usage guideline about operator confirmation.

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 enums and descriptions. The tool description adds behavioral context for each mode (e.g., TRUST auto-proceeds on WARN with a note, AUTO silently) and notes Business/Pro requirements for TRUST/AUTO, which extends beyond the schema.

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

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

The description clearly states the verb 'Set' and resource 'autonomy mode for one action class'. It distinguishes from sibling tools like setell_get_autonomy by focusing on mutating the mode. The explanation of modes (WATCH, TRUST, AUTO) provides specific context on what each mode 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 description gives clear context for when to use this tool (to change autonomy mode), but does not explicitly state when not to use it or suggest alternatives. It does include a guideline to 'Confirm with the operator before flipping', which adds usage nuance.

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?

Describes the partial patch and full-replacement semantics for lists, which is critical behavioral info beyond annotations. No contradiction with 'idempotentHint: true' and 'destructiveHint: 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?

Two sentences packed with essential information, front-loading the key behavior. No 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?

No output schema, but description provides sufficient context for correct usage. Could mention return value, but not critical for an update 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 coverage is 100%, baseline 3. Description adds value by explaining notes clearing behavior and giving examples for machines, finishing, and materials, enriching the parameter meaning.

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 is a partial patch of the operator's shop profile, using specific verbs like 'update' and resource 'shop profile'. It distinguishes from siblings by instructing to read 'setell_get_shop_profile' first and explaining the replacement behavior.

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 advises to read 'setell_get_shop_profile' first and send complete updated lists for array fields. It also mentions to confirm with the operator before writing, providing clear when-to-use and when-not guidance.

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