MisarReach MCP Server
Server Quality Checklist
Latest release: v5.1.1
- Disambiguation5/5
Every tool has a clear, unique purpose. Despite a large number, each operation is distinct—search vs. list, create vs. sync, update vs. move, preview vs. send—with explicit cross-references in descriptions to prevent confusion.
Naming Consistency4/5Most tools follow a verb_noun pattern (list_leads, create_deal, get_pipeline). Minor deviations like 'login' and 'auth_status' are acceptable, and the consistent use of 'get_' for status/config endpoints maintains predictability.
Tool Count2/5With 30 tools, the surface area is far beyond the ideal 3–15 range. While each tool is justified by the rich feature set, the sheer number overwhelms an agent and exceeds the rubric's threshold for 'too many'.
Completeness5/5The tool set covers the full lifecycle of lead generation, management, enrichment, outreach, deal tracking, pipeline management, autopilot, channel configuration, sales-agent administration, and authentication. No critical gaps are evident for the intended domain.
Average 4.7/5 across 30 of 30 tools scored. Lowest: 4.1/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 24 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral burden and does well: explains the browser opens, user must click 'Authorize', API key is delivered to client and persisted to ~/.misarreach/config.json. Discloses the credential storage side effect. Could add what happens on failure/cancel but covers the key concerns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no fluff, front-loaded with purpose. The first sentence establishes the core CTA clearly. Slightly redundant elaboration of the flow but each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an auth tool with zero required params and no output schema, the description covers the flow, side effects, and persistence adequately. Combined with full schema coverage, the agent has enough to invoke correctly. Minor gap: no mention of success/failure return behavior or how the agent knows auth succeeded.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, all three params (port, force, app_url) are described in the schema. The description adds context around port range and the force behavior (issues a new key) but doesn't materially exceed the schema. Baseline 3 is appropriate since schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'Authenticate with your MisarReach account via browser.' Explicitly distinguishes from API key copy-paste flow and explains the OAuth-like browser interaction. Distinct from sibling tools (logout, auth_status), making it unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
States when to use it (first-time auth or when re-authenticating) via the force parameter description. However, it doesn't explicitly compare against logout/auth_status or explain when NOT to use it (e.g., when credentials already present). Context is implied but exclusions are not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that this is a read-only status check (non-destructive), specifies what it returns (auth state + base URL), and indicates it returns actionable next steps on failure. It doesn't describe potential side effects but for a status check, the absence of side effects is well implied by 'Check'. Lacks some detail on what exactly the 'actionable next steps' contain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both earning their place. The first states the primary purpose, the second adds the behavioral nuance about returning next steps on failure. Zero waste, appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, the description is quite complete. It covers what it checks (auth, base URL) and behavior when unauthenticated. Minor gap: doesn't describe the exact return format, but with no output schema and a simple status-check purpose, this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
This is a zero-parameter tool, so the schema carries no parameter semantics to convey. The baseline for 0 params is 4. The description appropriately describes what the tool reports (auth state and base URL) without needing to explain parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks authentication status with MisarReach AND which API base URL is in use. It includes specific verb ('Check') + resource ('authentication with MisarReach') + scope ('API base URL'). It distinguishes itself from siblings like login/logout which are actual auth operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly signals this should be used first to verify auth state before other tools, and mentions 'actionable next steps when it is not' authenticated. It provides clear context but does not explicitly name alternatives or say 'when NOT to use'. However, the nature of a status-check tool makes its usage context fairly evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided (no readOnlyHint, destructiveHint, etc.), the description carries the full burden. It transparently discloses that this mutates local config state by deleting the stored key, and importantly clarifies the distinction between local logout and server-side revocation — this prevents the agent from assuming the credential is fully deactivated. It doesn't contradict any annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and every word earns its place. The first sentence states the primary action and target file path. The second sentence adds a critical caveat about server-side validity that prevents a dangerous misconception. No filler, no repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, this description is complete. It explains the action, the file modified, and the important caveat about server-side key validity. The only minor gap is not stating what the return value of logout looks like (success/failure), but with no output schema and a simple side-effect operation, the current description is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema coverage, so the schema fully documents the absence of inputs. The description appropriately explains what the (non-existent) parameters would control — nothing needs explaining. The description's value here is in the side-effect explanation rather than parameter semantics, which is appropriate for a zero-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: disconnects the client by deleting the stored MisarReach API key from a specific file path (~/.misarreach/config.json). It uses a specific verb (disconnect/delete) with an explicit resource, and it distinguishes itself from sibling tools like auth_status and login by being the logout counterpart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes clear when this should be used (to disconnect the client) and provides important exclusion context: it notes the key stays valid on the server and instructs revoking it in Settings → API keys to fully retire it. It doesn't explicitly name alternative tools, but the context of when to use vs. not use is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotentHint true. The description adds important context: it does not approve/undo actions, requires an API key, and returns a normal empty answer when no actions occurred. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear summary sentence, then adds purpose and caveats. Each sentence provides distinct value with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool, the description fully covers purpose, scope, safety, prerequisites, and error semantics. The lack of an output schema means return values aren't a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters and schema coverage is 100%, so description has little need to explain parameters. The baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states clearly that this tool retrieves the sales agent's actions taken today with summary stats, naming specific examples (actions taken, deals created, replies sent). It distinguishes itself from sibling config/process tools by framing itself as an audit trail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to use it for auditing and sanity-checking after enabling the agent, and notes it covers TODAY only, so not for historical reporting. However, it doesn't name a specific alternative tool for historical reporting, so it falls short of a full alternatives list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description enriches the annotation flags (readOnlyHint: false, idempotentHint: false) with concrete details: it 'ACTS on a real conversation,' can send messages or book meetings, 'CONSUMES AI CREDITS,' is 'not idempotent,' and requires an API key and confidence threshold. This far exceeds what annotations convey and prepares the agent for 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact at ~90 words and front-loads the primary action. It uses structured warnings with ALL CAPS ('CONSUMES AI CREDITS') and line breaks to emphasize risks. While clear, the ALL CAPS and em dashes make it slightly harder to parse quickly, though still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's high-stakes, side-effecting nature, the description covers all critical dimensions: real-world impact, cost, non-idempotency, authentication, and confidence threshold. It does not explicitly state a return value, but this is mitigated by directing users to get_sales_agent_actions for historical actions. Overall, very thorough for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full 100% description coverage for the single conversationId parameter. The description adds contextual context ('over one conversation') but doesn't add new syntactic detail about the parameter itself. Baseline 3 is appropriate because the schema carries the load, and no clarification is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear, specific verb+resource: 'Run the sales-agent pipeline over one conversation: decide the next action and carry it out.' It goes on to list concrete side effects (reply to prospect, create deal, book meeting) and names a sibling tool for past actions, fully distinguishing itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: 'call it only when the user wants the agent to take its turn on that specific conversation.' It also names the alternative, get_sales_agent_actions, for retrieving what the agent has already done, and clarifies it is not a dry run.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds value by explaining the idempotent behavior ('sending the same verdict twice is harmless') which aligns with and explains the annotation. It also discloses requirements (API key) and cost (no credits) beyond annotations. However, it doesn't detail what happens to the feedback record or any state changes, so a 4 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and structured with a clear opening sentence about purpose, followed by usage guidance, and then behavioral details. Every sentence carries weight, and it is front-loaded with the primary action. No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (simple write operation with three params), the schema fully describes parameters, and annotations cover safety and idempotency, the description provides sufficient context: purpose, when to use, what it doesn't do, and side effects. No output schema needed, and the description explains the long-term effect ('improves later output'), which is valuable. Complete for an agent to decide and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all three parameters (jobId, leadEmail, feedback). The description doesn't add much beyond the schema; it mentions 'feedback' as a verdict but doesn't elaborate on how jobId or leadEmail are used. Baseline 3 is correct when schema fully covers parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: recording feedback on AI-generated outreach messages as training signal. The verb 'Record' with the resource 'lead feedback' is specific, and it distinguishes itself from sibling tools like 'preview_message' and 'send_to_campaign' by clarifying it does not edit, resend, or delete the message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Use it when the user judges a drafted message — it improves later output rather than changing anything now.' It also clarifies what it does not do (edit, resend, delete, send to lead), which helps differentiate from similar messaging tools. This exceeds a 4 by providing both positive and negative conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds crucial behavioral details: it explicitly states the tool is a preview, generates different wording each time, and requires no API key. These insights go beyond the annotations and set clear expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with three focused paragraphs, but it contains some redundancy (e.g., repeating the preview nature in multiple places). It is not overly verbose, but could be tightened while maintaining clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, side effects (none), usage context, and generative behavior. It also notes the absence of an API key requirement, making it self-contained. No output schema exists, so return details are not expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage with descriptions for all parameters (name, role, company). The main description only restates that role and company are optional, adding no new semantics beyond what the schema already offers. Hence, it stays at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action and resource: 'Draft a sample AI-personalised outreach message for a named person.' It distinguishes from siblings by explicitly noting it's a preview and not sending anything, making its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Use it to check tone before committing to a sequence.' It also clarifies when not to use it (nothing sent, saved, or attached) and that the person need not exist as a lead, which helps in selecting this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by explaining the real-world impact of the settings (e.g., enabling starts responding, confidence threshold controls action threshold, reply limits cap sending). It also states that only passed fields are updated and that changes take effect immediately, providing clear behavioral expectations without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, starting with a clear one-sentence purpose, then elaborating on implications and safety. It is concise without unnecessary repetition, uses effective formatting (e.g., capitalized warnings) to highlight key points, and maintains focus on essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has 6 parameters with schema descriptions and no output schema, the description provides sufficient context for typical use: partial update behavior, side effects, and authentication requirement. It does not detail error handling or specific validation rules, but these are not critical for basic usage and are not indicated as required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides descriptions for each parameter, so the description does not repeat them. However, it adds important semantic nuance by stating 'only the fields you pass change', clarifying that all parameters are optional and the operation is a partial update. This is not explicit in the schema and enhances understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: changing the AI sales agent's settings, listing the specific settings (enable/disable, booking link, offer price, reply limits, confidence threshold). It distinguishes itself from the sibling 'get_sales_agent_config' by indicating it modifies values rather than retrieves them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on when to use this tool, such as 'Read the current config first' and 'only the fields you pass change', implying a read-before-write workflow. It does not explicitly mention alternatives but implies using the getter for reading. The warning about 'treat them as live' and 'safe to repeat' offers practical usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description adds critical behavior: each call creates a new deal without checking for duplicates, requires an API key, value is in minor currency units, and the created deal enters the pipeline at the first stage. This significantly enriches the agent's understanding of side effects and constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four focused sentences: purpose first, then usage guidance, then key behavioral details. Every sentence contributes unique information with no filler or repetition, making it easy to scan and apply.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, 1 required, no output schema, and basic annotations, the description covers the essential operational context: when to use, duplication risk, alternative tool, auth requirement, unit convention, defaults, return value, and pipeline placement. This is a complete picture for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters well. The description does add natural-language emphasis on leadEmail as the key identifying field and clarifies the default behavior for value/currency, but most of this repeats schema descriptions like 'Deal value in minor currency units (default 0).' The schema carries the main parameter burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Open a new deal against a lead's email address.' It clearly states the tool's function and differentiates from siblings by mentioning list_deals and update_deal, so the purpose is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit trigger: 'Use it when a conversation turns into a real opportunity worth tracking.' It also provides exclusions and alternatives: check list_deals first to avoid duplication, and use update_deal to change an existing deal. This is model usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the annotations: it consumes enrichment credits per call, requires an API key, updates the stored lead in place, returns it, and does not create duplicates — but running it twice still bills twice. This gives the agent crucial cost and side-effect information not present in the schema or annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three purposeful sentences with no filler: it front-loads the main purpose and fields, gives sequencing guidance, and then discloses cost and idempotency behavior. Every sentence earns its place and the warnings are directly actionable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with annotations already present, the description covers purpose, when to use, prerequisites, cost, mutation behavior, return behavior, and idempotency. There is no output schema, but the statement that it returns the updated lead is sufficient for this low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, leadId, is already fully described in the schema as a 'Lead UUID from list_leads,' so the description adds little new parameter-level meaning. With 100% schema description coverage, the baseline of 3 is appropriate because no additional parameter semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Fill in a saved lead's missing person and company detail' and lists concrete fields like seniority, department, LinkedIn, phone, company size, and industry. This specific verb-resource pairing clearly distinguishes it from sibling tools such as list_leads or discover_companies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to use the tool one lead at a time, after list_leads has supplied the id, and typically before writing outreach that needs context. It also gives a clear when-not-to condition: check the lead first, because enriching an already-complete lead wastes credits.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, and the description adds meaningful context on top: requires an API key, returns the whole board without pagination, lists all possible stages, and warns that money is in cents requiring division by 100. This goes well beyond the structured hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by usage guidance and key operational details. Every sentence adds value: board semantics, alternative tool guidance, auth requirement, stage list, and currency units. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and no output schema, the description fully covers the return shape (board grouped by stage with revenue totals), the stage enum, money unit quirks, and the lack of pagination. This is sufficient for an agent to invoke and interpret the result without further guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter workspaceId is already fully described in the schema as 'Optional workspace UUID to filter pipeline,' so schema coverage is 100%. The description does not add extra parameter semantics, keeping this at the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets the sales pipeline as a board, grouping deals by stage with revenue totals. It distinguishes itself from the sibling list_deals by explicitly describing this as the board view versus the flat list view.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance: use for 'how does the pipeline look' questions and stage-by-stage review. It also names the alternative list_deals for filtering or paging, explaining this tool returns the whole board.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), it adds 'Requires an API key' and 'Returns the configuration for the authenticated account,' clarifying authentication and scope. It also redundantly states 'changes nothing,' but the new auth/scope context earns credit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: purpose, usage guidance, and safety/auth/scope. Front-loaded with the main action and not bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only config tool with no params and no output schema, the description fully covers what it does, when to use it, safety, auth, and account scope. No significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has zero parameters and an empty schema (100% coverage). Baseline for 0 params is 4. The description reinforces 'takes no parameters' and implies why (account-based), though it doesn't need to explain params that don't exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Fetch the AI sales agent's current settings' – a specific verb and resource, and enumerates the exact fields (enabled, booking link, offer price, reply limits, confidence threshold). This clearly distinguishes it from the sibling write tool update_sales_agent_config.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Read this before update_sales_agent_config so you change one field without clobbering the rest, and to check whether the agent is enabled at all before expecting it to act.' This gives direct context and references the alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive. The description adds crucial context beyond annotations: 'costs no credits', 'starts nothing', 'Requires an API key', and 'Returns runs newest first with paging' — all useful behavioral details for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-paragraphed, and front-loaded with the primary purpose. Every sentence earns its place: purpose, usage guidance, alternatives, behavior, auth, and ordering. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description explains what is returned (status and result summaries), ordering (newest first), pagination, auth requirement, and credit cost. For a simple list tool with strong annotations, this is fully complete 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both limit and offset already described. The description adds minor context like 'newest first' and 'paging', but the parameters are fully understandable from the schema alone, so the description provides no significant extra meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists past and running autopilot runs with their status and result summaries. It distinguishes itself from siblings by explicitly referencing get_autopilot_status for single-run detail and start_autopilot for launching, making its scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use: to review past runs and to check for an in-flight run before starting a second one. Also names get_autopilot_status as the alternative for detailed run info, giving clear context vs. alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond those flags: it requires an API key, returns a revenue summary, and clarifies that money is in minor currency units (cents). It also explicitly states 'Reads only.' 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly structured: first sentence gives the functional definition, second covers usage guidance, third covers behavior and return details. Every sentence earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description fully compensates by explaining the return payload (deals plus revenue summary), the currency unit conversion, and the filtering/pagination behavior. It also positions the tool within the sibling set, making it complete 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already well-documented. The description adds general context about filtering by status and pagination, but it does not deepen the meaning of individual parameters beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('deals') and defines the output shape ('flat, paged array, optionally filtered by status, with revenue totals'). It explicitly distinguishes itself from the sibling tool get_pipeline, which returns the same deals grouped into stages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Use this when you want deals as data — to count them, filter one status, or page through many.' It also names the alternative (get_pipeline) for board-view needs, making the when-to-use-versus-alternative decision unmistakable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations carry readOnly, idempotent, and non-destructive hints. The description adds useful context: requires API key and connected account, empty result means no lists exist yet, and explicitly notes it costs no credits. Minor deduction for describing the read-only nature, which was redundant with the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core one-line definition, followed by scannable guidance on when to use it, with references to sibling tools and prerequisites. Every sentence contributes, including the empty-result edge case. Well-scoped for a zero-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless, side-effect-free list tool with strong annotations and no output schema, this description covers what an agent needs: purpose, when to use it (avoid duplicate lists), prerequisites (API key, connected account), behavior on empty results, and cost implications. No unnecessary output format explanation is needed given the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero-parameter tool, so baseline is 4 per the rubric. The description confirms this with 'takes no parameters' rather than remaining silent. No schema deductions needed for a parameterless and succinct tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource in sentence one: "List the Hunter.io lead lists connected to this account." Distinguishes itself from sibling tools by naming search_leads, create_lead_list, sync_lead_list, and list_leads explicitly, referencing their alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use guidance: use to find listId pre-sync, or to check for duplicates pre-create. Differentiation from siblings is explicit: "these are Hunter.io's lists, which are separate from the leads stored locally — list_leads shows those."
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already declare read-only, idempotent, and non-destructive, the description adds valuable context: reads only and costs no credits, requires an API key, returns specific fields (contact, company, enrichment, score), and treats empty page as a normal answer. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise yet information-dense: the first sentence front-loads the core function, the second paragraph clarifies usage vs. alternatives, and the third covers behavioral details. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers sorting (newest first), paging, search, filtering by job, auth requirements, response contents, and empty-page semantics. Given there is no output schema, the description sufficiently fills the gap for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds a use case for job_id ('Narrow to one search job...') and mentions paging/search, but this largely restates schema meanings without substantial new parameter-level detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States it lists leads already saved to the account, newest first, with paging and search. Explicitly distinguishes from search_leads by noting it does NOT find new leads, 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.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Use this to work with leads you already have' and contrasts with search_leads, which 'starts a job and costs credits.' Also explains narrowing results with job_id for a specific job.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (idempotentHint, readOnlyHint, destructiveHint), the description adds critical behavior: moving to closed/lost resolves the deal and affects open pipeline revenue, repeating the action is safe, and stages are not ordered allowing backward moves. It also states API key requirements. This enriches the annotations meaningfully.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and efficient: the first sentence nails the purpose, the second gives usage guidance and contrasts, the third details consequences and reversibility. Every sentence adds value without redundancy, and the length is commensurate with the tool's importance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only two parameters and no output schema, the description covers all necessary aspects: purpose, usage caveats, behavioral effects on deals and revenue, idempotency, and backward movement. It is self-contained and leaves no significant gaps for an agent to misinterpret.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides descriptions for both parameters (dealId as 'Deal UUID' and newStage as 'Target stage' with an enum). The description does not add further semantic detail beyond restating the tool's purpose, so it does not go beyond the schema's coverage. With 100% schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool moves a deal to a different pipeline stage, using the vivid analogy of dragging a card on the board. It explicitly distinguishes from sibling tools like update_deal, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: it is the tool for pipeline progression, contrasts with update_deal for value/notes, warns about the revenue impact of moving to closed/lost, and instructs to only do so when the user confirms the outcome. It also notes the tool can move deals backwards, giving clear context for when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses consequential behavior: leads on a running campaign can start receiving messages, the tool does not send or start anything itself, duplicates are avoided, leads must belong to the authenticated account, and importing dead emails damages sender reputation. This adds substantial context beyond the structured hints and does not contradict them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action, then efficiently covers consequences, exclusions, prerequisites, and warnings. Every sentence adds value, and the length is appropriate for the tool's consequential nature.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description fully covers what the tool does, its side effects, prerequisites, failure conditions, and related verification guidance. For a bulk mutation tool with this level of consequence, the description is complete and self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all three parameters with descriptions, so the baseline is 3. The description adds meaningful constraints not in the schema: the 500-lead batch limit, the requirement that every lead belong to the authenticated account, and the idempotent no-duplicate behavior. This raises it above the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Add saved leads to a campaign's contact list in bulk, up to 500 at a time.' It clearly distinguishes this tool from sibling lead-management tools by framing it as the step that puts leads into an outreach sequence, and it explicitly clarifies what the tool does NOT do (send or start the campaign).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives strong usage context: it explains that this is how leads enter an outreach sequence, warns about consequences, and instructs users to verify addresses with verify_emails first. It does not explicitly name alternative tools or state when not to use it, but the guidance is clear enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral detail beyond annotations: it writes local records, re-syncing refreshes rather than duplicates, requires an API key and connected account, and has no credit cost. It fully supports the idempotentHint and openWorldHint annotations 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose. Every sentence provides useful context: workflow position, effects, repeat-safety, prerequisites, and cost implications. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers what the tool does, why it is needed, the preconditions, side effects, idempotency, and billing implications. With a simple single-parameter schema and no output schema, this is complete enough for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter listId is already fully described in the input schema with 100% coverage. The description does not add meaningful parameter-specific semantics, which is acceptable given the schema already handles it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific action ('Import a Hunter.io lead list into local lead records') with a clear resource and effect. It also distinguishes from sibling tools like create_lead_list and list_lead_lists by explaining the sync relationship.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to run it ('after create_lead_list, or on any existing list from list_lead_lists') and explains why it is necessary ('Until a list is synced its contacts are invisible'). This gives the agent clear workflow context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful details beyond the read-only, idempotent, and non-destructive annotations: it consumes verification credits per address, requires an API key, returns 'undeliverable' as a successful result, and confirms nothing is sent to addresses. There is no contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the core purpose, then expands into timing, usage constraints, cost, auth, and output semantics. Every sentence contributes distinct information, with no redundant fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description explains what the return value is (a deliverability verdict per address) and the key semantic nuance that 'undeliverable' is still a successful result, not an error. Together with API-key and credit-cost information, the tool is fully usable by an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters fully, so this is at baseline 3. The description adds extra semantic value by clarifying that only one parameter should be used and that a batch of 20 costs 20 credits, which makes the `emails`-billing relationship explicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action and resource: checking whether email addresses are deliverable. It also states the one-at-a-time versus up-to-20-at-a-time scope, which clearly differentiates it from other lead/deal/send tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool ('Run this before a send to protect sender reputation') and gives the parameter usage rule ('Pass either email for one or emails for a batch, not both'). It does not explicitly name alternative tools or when-not-to-use cases, 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, but the description adds valuable context: 'Requires an API key', 'fetch_emails=true performs email lookups and COSTS CREDITS', and 'No lead is saved to the account by this call.' These disclosures about side effects and resource usage exceed 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-organized: a one-sentence summary, followed by usage context and important caveats (API key, credits, side-effect-free). No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters and no output schema, the description covers key aspects: purpose, alternatives, behavior with fetch_emails, and side-effect guarantees. It might have detailed error scenarios or result format, but it is complete enough for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining that 'filters combine with AND' and that fetch_emails has cost implications, which is not evident from the schema alone. This adds semantic depth to parameters beyond their type definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Find COMPANIES matching firmographic criteria via Hunter.io, optionally pulling contact emails for each.' It uses a specific verb and resource, and explicitly contrasts with sibling search_leads ('When they want named people, use search_leads'), distinguishing it from alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance: 'reach for it when the user is targeting organisations by industry, location, headcount or tech stack.' It also names an alternative ('use search_leads') and explains the AND behavior of filters, giving clear context for when to choose this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, but the description adds substantial behavioral context beyond that: reading does not affect the run, it keeps going, costs no credits, requires an API key, and an in-progress run is a normal response rather than an error.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and well-structured. Each sentence earns its place: it states the purpose, explains how to use it in a polling workflow, clarifies side-effect absence, notes credit usage, and sets expectations about in-progress runs. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description carries responsibility for explaining call semantics. It covers polling behavior, side effects, credits, error expectations, and API key requirements. It does not detail the exact response fields for progress/results, but the behavioral guidance is sufficient for low complexity and a single parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with runId described as 'Autopilot run UUID,' so the schema already carries the core meaning. The description adds useful operational semantics by instructing the caller to pass the runId and to poll with time between calls, which goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get the current progress and results of one autopilot run.' It uses a specific verb and resource, and the scope ('one autopilot run') distinguishes it from sibling tools like list_autopilot_runs and start_autopilot.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use it: 'This is how you follow a run started by start_autopilot: call it with the runId, leaving time between polls.' It also clarifies what this tool does not do (does not pause/stop/alter) and notes there is no stop tool, setting appropriate expectations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the annotations: each call creates a NEW list, names are not deduplicated, no local import occurs, no credits are consumed, and the return value includes the id needed by sync_lead_list. This aligns with idempotentHint=false and openWorldHint=true without contradicting any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence serves a purpose: defining the operation, clarifying non-side-effects, naming the caller prerequisite, explaining non-idempotency, listing requirements, and specifying the return value. It is front-loaded with the core purpose and remains compact despite covering several behavioral nuances.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter creation tool, the description is complete: it covers prerequisites, side effects, cost, non-idempotency, the relationship to sibling tools, and the exact return value needed downstream. With no output schema, describing the returned ID and its consumer is particularly valuable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of the single parameter, so the baseline is 3. The description adds meaningful semantics by warning that names are not deduplicated — the same 'name' value produces multiple lists, which is critical for an agent deciding whether to reuse a name. It slightly exceeds the schema-only baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource+state ('Create a new, empty lead list in Hunter.io') and clarifies what the tool does NOT do (populate the list, import anything). It also differentiates from the sibling sync_lead_list explicitly, making the tool's scope unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: 'Call list_lead_lists first' and notes that sync_lead_list handles actual importing. It also states prerequisites (API key, connected account), cost implications, and the non-deduplication behavior, which tells the agent when to call this repeatedly vs. when to use alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description adds important behavioral context: requires an API key, returns per-channel enabled/configured/delivery-count information, and warns that disabled channels silently deliver nothing. No contradiction with annotations; in fact, it reinforces the read-only safety profile with practical operational detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, purpose-driven paragraphs: the main capability, the recommended usage timing, and the safety/return summary. Every sentence adds meaningful information; no filler or redundancy beyond what annotations already covered.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by stating exactly what is returned: whether each channel is enabled, whether credentials are configured, and recent delivery counts. It also provides authorization context, behavioral caveats, and a clear relationship to update_channel, making the tool fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema already reflects this with an empty properties object; the description explicitly confirms 'takes no parameters.' Since there are no parameters to document, the description cannot add more value here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Report') and identifies the exact resource ('configuration, connection state and delivery stats for every outreach channel'), naming the channel types. It clearly distinguishes this tool from siblings by framing it as the status/pre-flight check before update_channel.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use the tool: 'Check this before relying on a channel' and 'natural first step before update_channel.' It also gives a concrete reason—disabled/unconfigured channels silently deliver nothing—and clarifies this is a read-only, no-change operation, which implies when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint, non-destructive), the description adds valuable behavioral details: it reads only, costs no credits no matter how often it is called, requires an API key, and returns a still-running job as a normal response rather than an error.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with the main purpose, then supplementary usage and behavioral details. Every sentence earns its place without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description sufficiently covers return values (run state, progress, leads found so far) and the asynchronous polling behavior. It also explains when the result is not an error, which is essential for correct agent behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully defines jobId with a description, so the bar is lower. The description adds meaning by clarifying the jobId comes from search_leads and is meant to be reused across repeated polling calls.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Poll one lead-search job for its progress and results.' It clearly identifies the tool as the companion to search_leads, distinguishing it from related tools like search_leads and list_leads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage guidance: call repeatedly with the jobId until the job finishes, leave a few seconds between polls, and polling harder does not make it faster. This is actionable context beyond the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint: false, idempotentHint: false, openWorldHint: true) are present; the description goes well beyond them by disclosing credit consumption ('CONSUMES SEARCH CREDITS on every call'), the side effect of each call starting a separate job, the API key requirement, and the additional AI credit cost of useAI. This is exactly the behavioral context an agent needs to avoid costly mistakes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place. The description is front-loaded with the most critical fact (async), then covers the polling workflow, sibling differentiation, cost warning, retry warning, auth, and AI-credit nuance — all in six tight sentences with strong formatting (caps, line breaks) that scannable. Zero fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool that starts an async job with no output schema and non-trivial side effects, the description is thorough: it explains the full request lifecycle, how to obtain results, when to use alternatives, billing implications, and auth prerequisites. Given the absence of an output schema and the tool's complexity (nested filters, async pattern), nothing significant is left undocumented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description earns a 4 by enriching the useAI parameter semantics: 'Setting useAI additionally spends AI credits to enrich and score the results as they arrive' — adding cost and timing context not in the schema. It also clarifies query's role in the async flow, though it stops short of documenting nested filter structure, which is handled well enough by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb+resource+outcome: 'Start an AI lead-search job and return its jobId immediately.' It immediately distinguishes itself from sibling tools by noting the async nature ('results are not in the response') and later contrasts with 'list_leads for ones already saved.' This clearly differentiates it from list_leads, get_search_job_status, and other siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to guidance ('Use it to find NEW leads; use list_leads for ones already saved'), a full workflow ('Poll get_search_job_status with the jobId until it reports completion, then read the leads with list_leads'), and a warning against misuse ('do not retry it as a way to check progress'). This is model-user-nudging at its best.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond annotations by revealing that changes affect live campaigns/autopilot runs, that disabling silently stops delivery, that enabling without credentials will not work, that the call is idempotent, and that an API key is required. These are valuable behavioral details not present in the annotation object.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet information-dense, with a clear opening line followed by consequence warnings, usage guidance, idempotence note, and auth requirement. Each sentence earns its place without redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter toggle tool with no output schema, the description is fully sufficient: it covers side effects, prerequisites, per-call limitations, idempotence, and authentication. The agent has everything needed to decide when and how to invoke it safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters already have clear descriptions. The description adds useful behavioral context for the 'enabled' parameter (e.g., idempotence, credential caveat) and emphasizes one-channel-per-call, slightly enriching the semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific action and scope: 'Turn one outreach channel on or off — WhatsApp, SMS or push.' It clearly identifies the resource and behavior, and it distinguishes this mutation tool from the sibling read-only tool get_channels_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit usage direction: 'Call get_channels_status first to see where things stand.' It also clarifies scope ('Handles one channel per call') and warns that disabling channels affects live campaigns, giving the agent clear context for when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses side effects beyond the annotations: it is a background operation that returns a count immediately, consumes AI credits, may bill again if rescoring, and requires an API key. The annotation readOnlyHint:false is consistent, and the description transparently explains the non-read-only, asynchronous, and potentially costly nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is thorough but well-structured, using clear sentences and sections (purpose, usage, background, credits, cap). Each sentence provides essential info without redundancy, making it appropriately concise for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary context: mode selection, background behavior, return value (count), how to get results later, credit consumption, API key requirement, and the 200-id cap. It leaves no major gaps for a tool with these side effects and asynchronous behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters (jobId and leadIds) are described in the schema and further elaborated in the description: jobId scores every unscored lead in a search job, leadIds scores specific leads. The description adds critical details like the mutual exclusivity, the 200-id cap, and the rescoring/billing consequences, enriching the schema's meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool queues AI qualification scoring for leads, distinguishing between scoring all unscored leads in a search job (jobId) or a specific set of leads (leadIds). The verb 'queue' and resource 'leads' are specific, and the two modes are explicitly contrasted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage instructions: pass jobId OR leadIds (not both), explains the background execution and that results are retrieved later via list_leads, warns about credit consumption and rescoring implications, and mentions the 200-id cap and API key requirement. This fully guides when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
This description goes far beyond annotations. It discloses critical behavioral traits: it sends real messages without returning for approval, it consumes credits and requires an API key, and it runs concurrently. Annotations only indicate readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false, but the description adds vital risk awareness (consequential, fire-and-forget) that the agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a brief overview sentence, then a high-risk warning paragraph, and finally a note about resource consumption. Each sentence earns its place, and the most critical information (sends real messages, requires explicit user request) is front-loaded. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description clearly states it returns a runId and how to monitor progress. It covers prerequisites (API key), side effects (credit consumption, concurrent runs), and constraints (goal text is the brief). This is complete for a complex, high-stakes tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already describes both parameters (goal and workspace_id) with 100% coverage, the description adds important context: the goal text is 'the entire brief' and gives an example, implying its critical role. It doesn't explain workspace_id further, but that's fine because the schema covers it. The description reinforces the meaning of goal beyond the schema's generic example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool starts an autonomous outreach run, distinguishes it from sibling tools (like list_leads or get_autopilot_status), and specifies the core functionality: the agent finds, contacts, and follows up with leads. The phrase 'FIRE-AND-FORGET' and 'SENDS REAL MESSAGES TO REAL PEOPLE' makes the resource and action unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use it (only when the user has explicitly asked for one and understands the goal) and when not to (it's consequential, not for casual experimentation). It also mentions alternatives for monitoring: 'watch progress with get_autopilot_status.' It notes that each call starts a separate run, implying warning against duplicate invocations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite having annotations for idempotency (idempotentHint: true) and openWorldHint, the description adds valuable context: 'Safe to repeat — the same call twice leaves the same deal.' It also explains the side effect of setting status to 'closed' or 'lost' ('marks the deal resolved and takes it out of open pipeline revenue'), which is critical for the agent to understand the impact of the operation. It also clarifies auth requirements ('Requires an API key') and the note-replacement behavior, which the annotations do not cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise but information-dense. Every sentence adds value: purpose, differentiation, side effects, idempotency, auth, units, and note-replacement behavior. It fits within a few lines and is front-loaded with the main verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description provides all necessary context: what fields can be changed, side effects (removing from pipeline), units, note-replacement behavior, auth requirements, and idempotency. There are no remaining ambiguities for an agent to handle this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all 4 parameters with descriptions (100% coverage), but the tool description goes beyond by explaining the units for value: 'value is in MINOR CURRENCY UNITS (2500 = $25.00)'. This is not obvious from the schema. It also clarifies the semantics of notes: 'Notes REPLACE the existing note rather than appending,' which is not in the schema. This is a great example of description adding value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Change a deal's status, value, or notes.' It uses a specific verb ('Change') and resource ('a deal'), and lists the exact fields it can modify. It also distinguishes itself from sibling 'move_deal_stage' by saying 'prefer move_deal_stage... for moving a deal along the pipeline board,' making it easy for an agent to choose between the two tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly contrasts with move_deal_stage, telling the agent when NOT to use this tool ('For moving a deal along the pipeline board prefer move_deal_stage') and what the alternative is for that use case. It also clarifies when this tool is the right choice: 'use this one for value and notes.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Misar-AI/misarreach-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server