MSIO

by brystal00

Overview Schema Related Servers Score Discussions

Python

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.0.0
Disambiguation5/5
Each tool targets a distinct resource or workflow, and direct overlaps (e.g., hcp_list_invoices vs hcp_list_job_invoices vs msio_ar_aging) are explicitly differentiated with USE WHEN/DO NOT USE WHEN guidance. The hcp_* resource actions and msio_* analytics tools are clearly separated in purpose.
Naming Consistency3/5
The hcp_* tools follow a predictable verb_noun pattern, while the msio_* analytics tools mostly use descriptive noun phrases rather than actions. The lone get_pricing_reference tool breaks the prefix convention, making the overall scheme mixed but still readable.
Tool Count2/5
36 tools is on the heavy side, especially when many are narrow read/list endpoints plus a separate analytics layer. While each tool is individually justified, the combined surface is larger than an agent can efficiently evaluate in one pass.
Completeness3/5
The server covers job creation, scheduling, notes, line items, tags, invoices, and a rich analytics layer, but several lifecycle gaps exist: no customer create/update, no estimate creation or update, no invoice get-by-id, and no update/delete operations for many core objects. These are notable but workable gaps given the read-heavy analytics focus.
Average 4.2/5 across 36 of 36 tools scored. Lowest: 3.5/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 3 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
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.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

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

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description claims 'Idempotent' while annotations set idempotentHint:false, a direct contradiction. It also discloses the return value and points to the removal sibling, but the contradiction undermines the behavioral metadata and makes the description untrustworthy.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three focused sentences with the core action front-loaded. Every sentence adds useful information: idempotency, return behavior, and the removal alternative. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with an output schema, the description covers the action, return behavior, and safe re-application. It doesn't mention prerequisites or permission requirements, but those are non-critical given the simple surface area. The contradictory idempotency claim slightly weakens overall completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Parameter schema coverage is 0% and the description does not define job_id or tag_id beyond the tool name's implication. It does not compensate for the absent parameter documentation, leaving the agent to infer the meaning of each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Apply a tag to a job', a specific verb and resource combination. It distinguishes from hcp_remove_tag_from_job and, by naming 'job' as the target, also separates it from hcp_apply_tag_to_customer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly notes that re-applying an existing tag is safe, which communicates when repeated calls are acceptable. It names the removal alternative but does not contrast with hcp_apply_tag_to_customer or mention prerequisite steps like creating the tag first.
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, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context beyond annotations: automatic pagination behavior and the cents-to-dollars price conversion. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no fluff. The core listing intent is front-loaded, followed by the two most important behavioral notes: auto-pagination and price unit conversion.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema and annotations cover return values and safety, so the description does not need to explain those. However, with six optional parameters and zero schema descriptions, the description is only minimally complete for helping an agent pass correct filters and date strings. It gives enough to attempt a call but not enough to be confident about parameter semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only says 'optional filters' without describing any specific parameter, format, or valid values. The parameter names like customer_id and scheduled_start_min are somewhat self-explanatory, but details like date format, work_status accepted values, or pagination semantics are left undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'List estimates with optional filters.' It distinguishes this from the sibling hcp_get_estimate by implying a multi-record listing operation. However, it does not explicitly contrast itself with other list_* siblings or state what kind of estimates are included.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes that filtering and pagination are optional ('optional filters', 'auto-paginates unless explicit page is set'), which gives useful operational context. It does not explicitly say when to prefer this tool over hcp_get_estimate or other list tools, nor does it mention any exclusions.
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 convey that the tool is read-only, idempotent, non-destructive, and open-world. The description adds a meaningful behavioral trait beyond those annotations: auto-pagination unless an explicit page is provided. It does not disclose defaults, ordering, or limits, but for a safe read operation the added pagination context is useful enough for a 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences with no filler. The core purpose is front-loaded, and the pagination behavior is stated in a compact, information-dense way.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low parameter count, presence of an output schema, and safety annotations, the description covers the main behavior. Still, it leaves important gaps: page_size is entirely unexplained, the page parameter's semantics are only partially inferred, and there is no mention of filtering, result limits, or default page size. It is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the burden of explaining the parameters. It only clarifies the role of 'page' by saying auto-pagination stops when an explicit page is set; it never explains 'page_size,' default values, indexing, or valid ranges. This is insufficient compensation for the complete absence of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation as 'List leads,' which is a specific verb-resource pairing and accurately conveys what the tool does. However, it does not distinguish itself from sibling list tools such as hcp_list_lead_sources or hcp_list_customers, nor does it define the scope of 'leads,' so it misses the differentiation required for a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage guidance is the auto-pagination rule: omit page to get automatic pagination, or set page for an explicit page. This implies when each pagination mode might be used, but there is no explicit guidance on when to choose this tool over hcp_create_lead, hcp_get_* tools, or other list tools.
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 cover read-only, idempotency, and destructive behavior. The description adds the critical pricing convention (input in cents, output converted to dollars), which is not present in the schema and does not contradict 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two compact sentences with the action front-loaded and the unit convention immediately after. Every sentence earns its place; there is no filler or redundant repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create-style operation with annotations and an output schema, the core behavior is adequately covered: what it does, the main input gotcha (cents), and the response conversion. It lacks usage and alternative context, but those gaps are more relevant to other dimensions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter-level semantic added is that price is in cents, which is essential for correct invocation. With 0% schema description coverage, the other five parameters rely entirely on their names and titles, so additional prose guidance would be valuable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (add) and resource (line item to a job) in a direct verb-object form. It does not explicitly contrast with sibling mutation tools like hcp_add_job_note or hcp_create_job, but the resource is distinct enough that the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to choose this tool over alternatives, and it does not mention prerequisites such as the job already existing. The usage scenario is only implied by the action phrase, 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?
The description discloses a useful behavioral trait not captured by annotations: 'Auto-paginates unless explicit page is set.' This adds meaningful context beyond the read-only, idempotent flags, though it does not address ordering, filtering, or response details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, with the core purpose front-loaded and the pagination behavior immediately after. No filler or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, read-only list operation with no required parameters and an output schema, the description is nearly complete. The main gap is the lack of usage guidance and page_size semantics, but the low complexity keeps this from being a significant deficiency.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description had to compensate for parameter meaning. It clarifies that setting an explicit 'page' disables auto-pagination, but it says nothing about 'page_size,' leaving its semantics to be inferred from the parameter name and type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'List lead sources.' It distinguishes the object from siblings like hcp_list_leads but does not explicitly differentiate itself from other list tools, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to call this tool versus alternatives such as hcp_list_leads or hcp_list_customers. The auto-pagination note is behavioral, not usage-oriented, and there are no exclusions or alternate tool recommendations.
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 readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond those annotations: auto-pagination behavior and dollar conversion of prices. This helps agents understand what happens during execution and how results are presented.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. It front-loads the primary purpose and follows with two high-value behavioral details: pagination and currency conversion. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main functional behavior, and the presence of an output schema and strong annotations reduces the burden on the text. However, the complete lack of parameter semantics for 8 optional filters leaves meaningful gaps, particularly for date format expectations and work_status values. This makes it minimally viable rather than fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden of explaining parameters. It only says 'optional filters,' which gives general awareness but does not explain the meaning, format, or allowed values for any of the 8 parameters. The schema only provides types and titles, which is insufficient for correctly constructing filter values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists jobs and supports optional filters, which identifies the core verb and resource. It does not explicitly differentiate itself from siblings like hcp_get_job, but 'list jobs' is a sufficiently distinct operation that the purpose is 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool: when a list of jobs is needed, with optional filters. It also explains pagination behavior, noting auto-pagination unless an explicit page is set. It does not explicitly mention alternatives or exclusions, but the usage context is clear enough for an agent to proceed.
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 establish the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral context: auto-pagination unless an explicit page is set, and the pro_ prefix used in employee IDs. This helps the agent interpret returned data correctly and contradicts nothing in 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. The action and resource are front-loaded, and each additional clause provides useful behavior or ID-format information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with optional pagination parameters and an output schema, the description covers the main invocation behaviors: pagination mode and ID prefix. It could be slightly more complete by explaining page_size, but no critical information is missing for making a correct call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate for the bare integer/null parameters. It explains that explicit page disables auto-pagination, giving page meaningful behavior, but page_size semantics remain undocumented. Partial coverage with a clear gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with 'List employees/technicians', naming the exact operation and resource. This clearly distinguishes it from sibling tools like hcp_list_leads, hcp_list_customers, and other list endpoints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, or when not to use it. The only behavioral note is about pagination, not about selection criteria or related tools.
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 indicate destructive behavior, but the description adds valuable specificity: 'Overwrites existing schedule — previous values are lost.' This tells the agent the exact consequence of calling the tool. The ISO 8601 format requirement is also useful behavioral/validation context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. The overwrite warning and the ISO 8601 format constraint are both essential and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core destructive behavior and a key format constraint, and output schema exists, so return values need not be explained. However, the optional employee_ids parameter is undocumented, and it is unclear whether omitting it clears employee assignments or preserves them — an important gap for a destructive schedule update.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for missing parameter documentation. It only clarifies that schedule times must be ISO 8601, which helps for scheduled_start and scheduled_end, but it does not explain the required job_id or the optional employee_ids parameter and its null/array semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Update a job's schedule.' It goes beyond the name by adding the overwrite semantics and scope, making it clear this tool is for replacing an existing schedule rather than creating a job or reading one. This differentiates it from siblings like hcp_create_job and hcp_get_job.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when an existing job's schedule needs to be changed, and the overwrite warning signals a destructive update. However, it does not explicitly state when not to use it, mention prerequisites, or name alternative tools for related operations.
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 non-obvious behaviors that annotations do not cover: the API silently drops description on POST, and the tool later records it as an internal note. It also warns about cents-to-dollars conversion, which is the kind of side-effect an agent must know before calling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all substantive: the operation, the required customer identifier, and two caveats. The description is front-loaded and contains no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description captures the critical gotchas for hcp_create_job, but for a 9-parameter create tool with no schema descriptions, it still leaves scheduled_start/scheduled_end format, employee_ids/tags expectations, and the scope of the price conversion unstated. Output schema presence covers return shape, but invocation details remain only partially complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no parameter descriptions (0% coverage), so the description must compensate. It adds important meaning for customer_id (cus_ prefix) and description (silently dropped and stored as internal note), but it leaves the other seven parameters to their titles; formats and enumerations are still unspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with 'Create a new job,' a specific verb-and-resource statement that leaves no ambiguity about the action. It is immediately distinguishable from siblings such as hcp_get_job, hcp_create_lead, and hcp_update_job_schedule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage guidance is a hard prerequisite: customer_id must be provided with a cus_ prefix. It does not state when to prefer this tool over alternatives or when not to use it, and no sibling exclusions are mentioned.
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 disclose the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false). The description adds one genuinely useful behavioral detail beyond the annotations: 'Prices converted from cents to dollars,' which tells the agent the returned data is transformed. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the action front-loaded and the conversion behavior delivered in a single clause. Every word earns its place; there is no filler or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two required string params, an output schema covering return values, and annotations covering the read-only/idempotent profile, the description is mostly complete. It adds the important cents-to-dollars transformation, but lacks explicit routing guidance and does not clarify the estimate-option ID hierarchy. These are modest gaps for a tool this simple.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden for explaining estimate_id and option_id, but it does not compensate. It never explains what the two IDs mean, how they relate (e.g., which option belongs to which estimate), or where to obtain them. The parameter names are mildly self-explanatory, but no relationship or format guidance is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (list), resource (line items), and scope (for a specific estimate option). The 'estimate option' scoping distinguishes it from the closest sibling hcp_list_job_line_items as well as estimate-level siblings hcp_list_estimates and hcp_get_estimate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The scope phrase implies when to use it — when you need line items for a particular estimate option — but there is no explicit when-to-use guidance, no exclusion criteria, and no mention of alternatives such as hcp_list_job_line_items or hcp_get_estimate. Usage is implied, 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?
Annotations already signal readOnlyHint=false and destructiveHint=true; the description aligns and adds useful behavioral context by stating that the operation occurs 'after removal' and that the remaining tags are returned. This goes beyond what annotations alone 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The action is stated first and the return behavior is a meaningful second sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-required-parameter destructive operation with an output schema, the description covers the core behavior and return value. It does not address edge cases like removing a non-existent tag, but the idempotentHint and sibling list_tags tool reduce ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not elaborate on job_id or tag_id, such as how to obtain valid values or whether IDs refer to internal systems. The parameter names are somewhat self-explanatory, but the description fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Remove a tag from a job' and even states the return value ('remaining tags'). It is immediately distinguishable from sibling tools like hcp_apply_tag_to_job and hcp_list_tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended context is implied by the verb 'remove', but the description does not explicitly name alternatives or when not to use this tool. An agent can infer use for removing tag associations, but no direct routing guidance is provided.
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?
The description goes beyond the annotations by warning that HCP expects nested customer and address objects, which is not apparent from the flat input schema. This is a valuable behavioral disclosure for constructing the request. It does not describe error or duplicate-creation behavior, but the annotations already signal the mutating, non-idempotent 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action, no filler. The required-field clarification and the nested-object warning are both high-value and earn their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 13-parameter creation tool with zero schema descriptions, the description is thin. It provides the essential required field and the nesting expectation, and the output schema covers return values, but an agent still lacks a clear picture of the request payload shape and optional-field semantics. Enough for a basic call, but with meaningful gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description needed to compensate, but it only highlights customer_name and loosely groups address fields. The semantics of notes, source, priority, employee_id, job_type_id, and customer_email/phone are left entirely to their parameter titles. This is inadequate for 13 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Create') and resource ('lead'), and it immediately identifies customer_name as the only required field. It clearly distinguishes this tool from the many read-only hcp_get_*/hcp_list_* siblings and from the other create tools (hcp_create_tag, hcp_create_job).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The use case is self-evident: use this tool when creating a lead, and there is no sibling lead-creation alternative to route around. The nested-object note adds a practical usage prerequisite. However, it does not explicitly state when not to use it or mention any fallback alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is well covered. The description adds only the 'cus_ prefix' detail, which is parameter-format context rather than behavioral disclosure. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence with no filler. The verb, resource, and key ID format detail are all front-loaded, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple one-parameter, read-only getter with rich annotations and an output schema. The description covers the essential operation and ID format. The only minor gap is explicit guidance on when to use this instead of hcp_list_customers or how to handle a nonexistent ID.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It does by specifying the expected 'cus_' prefix on customer_id, adding meaning beyond the bare 'Customer Id' title. For a single required string parameter, this is sufficient to make a correct call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), a specific resource ('a single customer'), and the ID format ('cus_ prefix'). This clearly distinguishes it from hcp_list_customers and other get_* sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for fetching one customer when an ID is already known, but it does not explicitly say when to use it versus alternatives like hcp_list_customers or how to obtain the customer_id. Usage context is present only implicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully established and the description does not contradict any of it. The description adds the customer scoping and the cus_ prefix requirement, which is useful, but it does not disclose pagination, result limits, or any other runtime behavior beyond what annotations cover — a moderate value-add.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence with the verb and resource front-loaded and the ID-format note tucked into a parenthetical. There is zero wasted wording, and every element earns its place for a simple read operation backed by rich annotations and an output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, read-only tool with a full output schema and comprehensive safety annotations, the description covers the essentials: what is listed, for whom, and the expected ID format. Minor omissions such as pagination and limit behavior are minor given openWorldHint and the output schema's presence, so nothing materially blocks correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides only the title 'Customer Id' for the sole required parameter. The description compensates by specifying the cus_ prefix format, which is the critical semantic detail needed to call the tool correctly. It does not go further (e.g., that the customer must exist), but for a single-parameter tool, the prefix hint is meaningful compensation for the schema's silence.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List'), a clear resource ('service addresses'), and a scope ('for a customer'), so an agent immediately knows what the tool returns. The parenthetical '(cus_ prefix)' adds a distinguishing detail about the expected ID format. Among siblings such as hcp_list_employees, hcp_list_leads, and hcp_get_company, none target addresses, so this tool is clearly differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use case is implied — call this when a customer's service addresses are needed — but the description offers no explicit when/when-not guidance, exclusions, or named alternatives. Since no sibling tool competes for the same task, the ambiguity is low, but the guidance is still left to inference rather than stated, which keeps this at a minimal-viable level.
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 read-only, idempotent, and non-destructive behavior. The description adds real behavioral context beyond those annotations by disclosing auto-pagination and the 'unless explicit page is set' override. This gives the agent useful operational knowledge without contradicting the annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, both substantive. 'List customers with optional search' states the core purpose, and 'Auto-paginates unless explicit page is set' adds the most important behavioral nuance. There is no filler, repetition, or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only listing tool with an output schema and strong safety annotations, the description is mostly sufficient. It covers purpose, search capability, and pagination behavior. It falls slightly short of full completeness because it does not describe page_size behavior or clarify how search interacts with pagination, but these are minor gaps given the output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It successfully clarifies that 'q' is the optional search parameter and that 'page' controls pagination. However, 'page_size' is left undocumented except for its property name, and the exact search semantics or pagination defaults are not explained. Partial compensation only.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the exact verb and resource: 'List customers', and adds 'optional search', which makes the intent unmistakable. It is clearly distinguishable from sibling tools like hcp_get_customer (single record fetch) and hcp_list_employees (different resource). No ambiguity remains about what operation this tool performs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: call this when you need a list of customers, optionally filtered by search. However, it does not explicitly state when to prefer it over alternatives like hcp_get_customer, nor does it mention any exclusions or prerequisites. The guidance is present only implicitly through the verb and resource.
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 cover readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral detail beyond that by disclosing price conversion from cents to dollars and explaining that the native HCP response shape is normalized. This helps the agent understand the actual output transformation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The core action is front-loaded, and the note about unit conversion and response normalization earns its place by providing operationally relevant detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one required parameter, annotations declare safety, and an output schema exists, so return-value details are already handled. The description covers what the tool does, the key unit transformation, and the normalization behavior, leaving no significant gap for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the lack of parameter documentation. It only says 'for a job,' which gives broad context but does not explain the job_id parameter's format, source, or expectations beyond the name itself. Minimal additional meaning is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and identifies the exact resource: 'line items for a job.' This clearly distinguishes it from siblings like hcp_get_job, hcp_list_job_invoices, and hcp_list_estimate_line_items, which target different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when line items for a specific job are needed, and the sibling list hcp_list_estimate_line_items suggests an alternative. However, it does not explicitly state when to prefer this tool over alternatives or 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable non-obvious insights: automatic pagination unless a page is specified, and the tag_ prefix convention for IDs. This is meaningful behavioral context beyond the structured 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each earning its place: the first states the operation, the second adds critical behavior and ID format. Front-loaded and free of filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list endpoint with a rich output schema and read-only annotations, the description is mostly complete. Auto-pagination and ID prefix are covered. The only omission is the meaning of page_size, which is minor since the tool works without it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter documentation. It only explains the page parameter implicitly through the auto-pagination note, but page_size is not addressed at all. This leaves a notable gap in understanding how to control pagination.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List all tags' uses a specific verb and resource, clearly identifying the tool's action. It distinguishes itself from the many other list_* siblings by naming the exact entity type (tags) and scope (all tags).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'List all tags' provides clear context for when to use this tool. The auto-pagination note also guides whether to pass an explicit page. It doesn't explicitly name alternatives, but there are no sibling tools that list tags, so exclusion guidance is not critical.
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 the tool read-only, idempotent, and non-destructive, so the description does not need to restate safety. It adds useful behavioral context: pricing is historical, specific to the south Alabama contractor market, and must be adjusted for other regions. This goes beyond the structured 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core action, and organized into helpful USE WHEN / DO NOT USE WHEN / GOTCHAS sections. Every section earns its place, and the structure makes it easy for an agent to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Usage guidance and gotchas are strong, and annotations plus an output schema reduce the need to describe return values. However, the lack of parameter-level explanation for 'kind' and 'unit_type' leaves an agent guessing about valid values and combinations, so the description is not fully complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden of explaining parameters, but it only implicitly references service_category through 'what do we charge for X?'. It does not explain the meaning of 'kind' (default 'labor') or 'unit_type', nor how they affect the lookup. This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Look up historical pricing from the south Alabama contractor line item corpus.' It clearly identifies the tool's function and differentiates it from job-line-item lookups by naming the sibling alternative in the DO NOT USE section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit USE WHEN scenarios are listed (generating estimates, validating pricing, comparing job costs, 'what do we charge for X?'), and a DO NOT USE WHEN exclusion names the correct alternative tool. This leaves no ambiguity about when this tool should be selected.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a mutating operation (readOnlyHint=false, idempotentHint=false). The description adds useful visibility context for note_type but does not disclose additional behavioral details such as whether customer notes trigger notifications, whether notes can be edited or deleted, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence states the purpose, and one sentence covers the key parameter nuance. Every word earns its place and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter tool with an output schema, the description covers the essential purpose and parameter semantics. It could add slightly more context about the effect of the operation, but nothing critical is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates for the most ambiguous parameter by defining note_type values and their meanings. The note and job_id parameters are self-explanatory from their names, so the missing schema descriptions are not a major blocker.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Add a note to a job.' It also clarifies the two note_type variants, so there is no ambiguity about what the tool does or how it differs from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context by explaining that 'internal' notes are staff-only and 'customer' notes are visible to the customer. It does not explicitly list alternatives or exclusions, but for this simple tool the guidance is sufficient.
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 cover read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context by disclosing that prices are converted from cents to dollars, which affects how the agent should interpret the response. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one tightly written sentence with no filler: it states the action, the resource, the key, and an important output detail. Every clause earns its place, and the primary purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only getter with a full output schema, the description plus annotations are nearly complete. The only minor gap is not noting that the job_id typically comes from hcp_list_jobs, or behavior when the ID is not found, but these are not critical for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the burden. The phrase "by ID" clarifies that job_id is the unique selector for the job, adding slight meaning beyond the parameter name and type. However, it doesn't explain where to obtain the ID (e.g., from hcp_list_jobs) or any format expectations, making it minimally adequate for a single self-explanatory parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: "Get a single job by ID." This clearly distinguishes it from sibling list tools like hcp_list_jobs and hcp_get_customer, since it targets one job by its unique identifier. The additional note about price conversion is a useful extra detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use case is clear: when you need one specific job and know its ID. It doesn't explicitly mention alternatives or exclusions, but the precondition (having a job ID) is implicitly stated. The context is sufficient for an agent to know this tool is not for listing multiple jobs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds the filtering behavior but not much additional behavioral context; it is consistent with annotations 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two brief sentences with no filler. The main action and resource are front-loaded, and the optional filter is stated compactly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with one optional parameter, rich annotations, and an output schema, the description is nearly sufficient. It could be slightly more complete by explicitly stating what happens when parent_uuid is omitted, but the word 'optionally' covers the main intent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only provides the parameter name, type, and default, with no description. The description adds meaningful semantics by explaining that parent_uuid optionally filters the returned categories by parent category.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('List'), a specific resource ('material categories'), and the source ('HCP price book'). It clearly distinguishes this tool from the many sibling list tools, which target different entities such as employees, leads, or customers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use it: whenever material categories from the HCP price book are needed. The optional parent_uuid filter provides helpful context, though it does not explicitly state exclusions or name alternative tools.
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 establish readOnly, idempotent, and non-destructive behavior. The description adds behavioral detail by explaining exactly what the scan returns and introduces the threshold concept for staleness. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler. The purpose and return categories are front-loaded, and the usage guidance is compact and actionable. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is strong for tool selection and safety, and the output schema covers return details. However, with six optional parameters and zero schema descriptions, the lack of parameter guidance makes the definition incomplete for confident invocation beyond defaults.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter meaning. It hints at age_threshold_hours via the 'after threshold' phrase, but status, customer_id, date_range_start/end, and max_estimates lack any semantic explanation. Parameter names are somewhat self-explanatory, but the description leaves too much to inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Scan estimates and flag those needing follow-up') and identifies two concrete output categories: stale sent estimates and approved-but-unscheduled estimates. It also explicitly distinguishes itself from hcp_get_estimate, 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use triggers ('pending estimates, revenue at risk, stale quotes, or what needs attention') and an explicit when-not-to-use condition with a named alternative ('looking for specific estimate details (use hcp_get_estimate)'). This is model guidance for tool selection.
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 establish this is a non-read-only, non-destructive write operation. The description adds valuable behavioral context beyond annotations by disclosing that duplicate names return 422 and that tag names are case-sensitive, which meaningfully affects invocation and error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two short sentences with no wasted words. The primary action is front-loaded, and the key behavioral details follow immediately. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter creation tool with an output schema and clear annotations, this description is complete enough for correct invocation. It conveys the action, the uniqueness rule, and the case-sensitivity rule. No critical missing information appears for an agent to select and call it properly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no description for the required 'name' parameter, so the description must carry semantic weight. It does so by clarifying that names are case-sensitive and that duplicates are rejected, giving the agent important constraints that the schema alone omits.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation ('Create a new tag.') with a specific verb and resource, and it distinguishes the tool from siblings like hcp_apply_tag_to_job and hcp_apply_tag_to_customer. The additional duplicate and case-sensitivity details further clarify the tool's unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied: use this when a new tag needs to be created before applying it to jobs or customers. However, there is no explicit guidance about when not to use this tool or when to prefer a sibling such as hcp_list_tags to check existing tags first.
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, destructiveHint false), the description discloses material runtime behavior: automatic pagination, behavior change when an explicit page is provided, the HCP-enforced maximum page size, and the expected ISO 8601 format for last_polled_at. These details are not present in the annotations or schema and materially change how an agent should call the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, with the core purpose first and the most actionable constraints after. Every sentence contributes operational value: what the tool does, how pagination behaves, and which parameter enables incremental polling. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, has an output schema, and strong annotations. The description covers the key operational details an agent needs: pagination defaults, hard API limit, and the incremental polling entry point. It is slightly incomplete in not stating what happens when last_polled_at is omitted, but given the schema marks it optional and output schema exists, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the schema's lack of parameter documentation. It explains last_polled_at with format and purpose, clarifies page via auto-pagination behavior, and constrains page_size with the HCP limit. It does not fully document every nuance, such as default values, but it adds meaning beyond the bare schema titles and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List events with incremental polling.' The event resource is distinct from sibling list tools, though it does not explicitly compare itself to any sibling such as hcp_list_employees or hcp_list_customers. The core purpose is clear but sibling differentiation relies on resource naming rather than explicit contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: incremental consumption via last_polled_at, auto-pagination unless an explicit page is set, and an HCP page_size ceiling of 50. It does not explicitly state when-not-to-use this tool or name alternatives, but the usage conditions are specific enough to guide correct invocation.
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 readOnly/idelmpotent/non-destructive, so the description is free to add value about behavior. It discloses that it avoids pagination and that prices are converted from cents to dollars, which are meaningful behavioral details beyond the schema and annotations. No contradiction found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise, front-loaded sentences. The first names the operation and scope; the second explains performance and data-format benefits. No filler or repetition of annotations or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only tool with an output schema and strong annotations, the description covers its scope, benefit, and a key output transformation. Nothing essential is missing 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, job_id, is self-explanatory from its name and the description's 'for a specific job' phrase. However, schema description coverage is 0% and the description does not elaborate on the job_id format, origin, or any constraints. The single obvious parameter keeps this at an adequate 3 rather than higher.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States the verb 'List' and the exact resource 'all invoices for a specific job', making it immediately distinct from the broad hcp_list_invoices sibling. The benefit of avoiding full-list pagination is also made explicit. This is a highly clear purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly implies when to use it: when invoices for a single job are needed, rather than paginating the full invoice list. It contrasts with the alternative full-list approach, though it does not name the sibling tool explicitly or state exclusions. Strong but not fully explicit.
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 readOnly, idempotent, and non-destructive behavior. The description adds useful context beyond annotations by stating the operation is tied to the authenticated API key and enumerating the returned fields (name, timezone, address, settings).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The core action and resource are front-loaded, followed by return contents and the parameter note. Every sentence contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool with an output schema, the description covers purpose, auth context, return values, and parameter expectation. An agent has everything needed to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema carries no parameter details. The description explicitly states 'No parameters needed,' which removes any ambiguity about invocation. This matches the baseline for a zero-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and a distinct resource ('company profile for the authenticated API key'), making it unambiguous. It also lists what is returned, which helps distinguish it from sibling get/list tools like hcp_get_job or hcp_get_customer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: it is the tool for retrieving the authenticated account's company profile. It does not explicitly mention alternatives or exclusions, but given the unique resource and zero parameters, the usage context is sufficiently 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 establish this is read-only, idempotent, and non-destructive. The description adds a meaningful behavior beyond those annotations: prices are converted from cents to dollars, which an agent would not otherwise know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, two clauses, no filler. The purpose and the key output behavior are both delivered without wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read tool with an output schema and safety annotations, the description covers everything needed to invoke it correctly. No pagination, mutation, or complex precedence concerns apply.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines estimate_id as a string with no further documentation. The description compensates by explaining the expected format ('csr_ prefix'), which gives the agent concrete guidance beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Get'), a specific resource ('a single estimate'), and the lookup key ('by ID'), with the useful csr_ prefix detail. This distinguishes it from list-style siblings like hcp_list_estimates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'single estimate by ID' clearly implies this tool is for point lookups when an estimate ID is already known, rather than for enumerating estimates. It does not explicitly name hcp_list_estimates as the alternative, so it stops short of full exclusion 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 goes beyond the annotations by explaining the GET+PATCH merge strategy, why it is needed (HCP PATCH replaces the entire tags array), and that the tool deduplicates before writing. This gives the agent a precise model of side effects and safety behavior. The destructiveHint annotation is not contradicted; rather, the description explains the destructive risk of the underlying PATCH and how the tool mitigates it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, all informative and non-redundant. The purpose is front-loaded, the critical PATCH caveat is explained in context, and the deduplication behavior is stated without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool, the description covers the essential invocation details: target customer, tag values, merge behavior, and deduplication. It does not describe the return value or error behavior, but those are not required for correct invocation and the annotation set already conveys idempotency and write-side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero description coverage in the schema, the description compensates well for the tags parameter: it clarifies that tags are arbitrary strings, not tag_ IDs, and that duplicates are removed. The customer_id parameter is not elaborated, but its name and schema title make its meaning self-evident.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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 tags to a customer.' It clearly distinguishes this from the sibling hcp_apply_tag_to_job by scoping to customers, and the additional details about merging, deduplication, and tag semantics make 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The first sentence and tool name establish the exact use case: applying tags to a customer. It does not explicitly name alternatives or say 'when not to use,' but the customer-versus-job distinction is clear from the sibling list and the description. The note that tags are arbitrary strings also implicitly guides usage by telling the agent no pre-created tag IDs are needed.
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 meaningful behavioral details: no server-side filtering, invoice items are inline so no nested calls are needed, and prices are converted from cents to dollars. These are non-obvious behaviors an agent must know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, each adding distinct value: what the tool does, its limitation, the alternative, and two important data-format traits. It is front-loaded and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the read-only annotations, and only two optional pagination parameters, the description covers the essential call-time knowledge. It explains the main caveats (no filtering, inline items, currency conversion) and routes to the correct sibling when needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for parameters, so the description carries the burden. It only implies page/page_size relate to pagination via 'No server-side filtering available', but does not explain page semantics, zero-indexing, or pagination behavior. The two optional parameters remain mostly undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'invoices', and differentiates itself from the sibling tool hcp_list_job_invoices by noting the alternative for job-specific invoices. This is a specific, unambiguous purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the agent when not to use this tool: for job-specific invoices, use hcp_list_job_invoices(job_id) instead. It also states that no server-side filtering is available, so the agent knows pagination is the only control. This is strong 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?
Annotations already mark read-only/idempotent/non-destructive, and the description adds non-obvious behavioral facts: the invoice endpoint has no server-side filters, large accounts are capped at max_invoices, and metadata.coverage_pct must be checked. This goes beyond what any annotation or schema field conveys.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Each section (purpose, use-when, not-use-when, gotchas) is separate and front-loaded with the most important operation. No sentence is redundant; the content is dense but organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, return-value documentation is not required here. The description covers selection criteria, the alternative tool, and the critical data-completeness limitation (cap and coverage percentage), giving an agent enough context to choose and invoke the tool safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description needed to clarify the five parameters. It only elaborates max_invoices (cap) and indirectly payment_terms_days via 'overdue'; customer_id, include_zero_amount, and minimum_amount_cents are left entirely to their schema titles and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Bucket overdue invoices by age for accounts receivable analysis.' This clearly identifies what the tool does and its domain, and the DO NOT USE clause differentiates it from hcp_list_invoices, so an agent can distinguish it from 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'USE WHEN' enumerates concrete scenarios and question phrasing ('How much money is owed?', AR review, collection priority, cash flow). 'DO NOT USE WHEN' explicitly routes to hcp_list_invoices for specific invoice lookup, giving both positive and negative selection criteria.
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: v0.1.0 is language-only, every tier returns unit_price=null, the AI must not invent dollar amounts, and pricing must be aggregated from the contractor's own past HCP jobs. This is exactly the kind of hidden behavior an 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear USE WHEN, DO NOT USE WHEN, and GOTCHAS sections. The main purpose is front-loaded, and every sentence carries actionable information without fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and annotations cover read-only/idempotent safety, the description covers purpose, boundaries, pricing constraints, and directive guidance thoroughly. It is not fully complete because conditions is an input parameter that remains undefined, but overall the agent has enough context to call the tool safely and effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no parameter descriptions, and the description only partially compensates. It clarifies service_category through 'same category' and job_description as scope language, but the optional conditions parameter is never explained. This leaves a meaningful gap for an agent trying to understand what values conditions should contain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: generating a Good/Better/Best three-tier estimate skeleton, and immediately qualifies it as language-only. It differentiates itself from HCP tools and get_pricing_reference by stating that it is not an HCP write and not a historical pricing lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit USE WHEN and DO NOT USE WHEN sections tell the agent exactly when to invoke this tool versus when to avoid it. It names the exclusions (creating an estimate record in HCP, looking up raw historical pricing) and provides a runtime alternative for grounding pricing from past HCP jobs.
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 establish readOnly, openWorld, idempotent, and non-destructive traits. The description adds valuable behavioral context beyond that: projection uses a simple moving average (not ML), accuracy degrades with sparse data, and pipeline figures reflect scheduled jobs only. These gotchas help the agent set expectations and avoid misinterpreting results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and highly structured, with clear USE WHEN, DO NOT USE WHEN, and GOTCHAS sections. Every sentence carries meaningful guidance, and the most important purpose statement is front-loaded. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return-value details are not needed. The description covers purpose, usage boundaries, and key behavioral limitations. However, the meaning of 'pipeline' in 'Pipeline shows scheduled jobs only' is somewhat unclear, and employee_id filtering is not explained. These are minor gaps given the tool's overall simplicity and the presence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate, but it only indirectly addresses parameters: 'Accuracy decreases with fewer months of data' hints at lookback_months. The names lookback_months and projection_months are self-explanatory, and employee_id has a default of null, but the description never explicitly maps parameters to behavior or clarifies how employee_id filters the analysis. This is a partial, not full, compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The opening line, 'Historical revenue analysis with trend detection and simple projection,' states a specific verb and resource, making the tool's function immediately clear. The DO NOT USE section further distinguishes it from siblings like hcp_get_job and hcp_list_invoices, so an agent can disambiguate without inspecting schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The USE WHEN list covers concrete intents ('How's business?', revenue trends, forecasting, seasonal analysis, growth questions, financial planning), while DO NOT USE WHEN explicitly names alternatives with conditions ('specific job revenue' → hcp_get_job, 'invoice details' → hcp_list_invoices). This gives the agent clear decision rules for selection.
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?
Goes beyond the readOnlyHint and idempotentHint annotations by disclosing the default date range (today CT), that the date filter uses scheduled date rather than completion date, and that $0 jobs are still flagged. These are valuable behavioral caveats not visible in annotations or schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose and uses concise labeled sections for usage and gotchas. There is no filler; each line adds operational value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and safety annotations provided, the description covers the most important invocation details: when to use, when not to use, and behavioral gotchas. The only minor gap is that it does not explicitly explain the remaining filter parameters, though their names are reasonably self-explanatory.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning for date_range parameters by stating the default and filter behavior, and for minimum_job_value via the $0 jobs gotcha. However, assigned_employee_id is left entirely to inference and minimum_job_value semantics are only partially disclosed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and object: 'Detect completed jobs with no invoice' and ties it to the business goal of unbilled revenue. It clearly differentiates from siblings by explicitly directing away from job details and invoice details 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'USE WHEN' scenarios including end-of-day checks and revenue leakage, and 'DO NOT USE WHEN' guidance with specific alternative tools. This leaves no ambiguity about when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds important behavioral caveats: the classification is regex-based rather than AI-based, and roughly 38.8% of jobs fall into a general catch-all category. This is exactly the kind of non-obvious behavior an agent needs to set expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, well-structured, and front-loaded with the core purpose, followed by return details, usage guidance, and gotchas. Every sentence adds actionable information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one simple parameter, a clear output schema, read-only annotations, and explicit usage guidance, the description covers everything needed to select and invoke the tool correctly. It also exposes the key reliability caveat (regex-based, catch-all frequency), making the tool's limitations transparent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has only one parameter, job_id, with a clear title and required flag. The description reinforces that the tool operates on a job, and the parameter is self-explanatory as a job identifier. Although the description does not provide detailed format guidance, the single simple parameter makes that unnecessary.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Classify a job into one of 13 plumbing service categories'), which precisely states what the tool does. It also differentiates from nearby siblings by naming hcp_get_job and hcp_list_jobs as tools for different needs, leaving no ambiguity about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides USE WHEN and DO NOT USE WHEN guidance, including concrete alternatives (hcp_get_job for job details, hcp_list_jobs for listing jobs). This gives an agent clear routing criteria without needing to infer intent.
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, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable operational context beyond those: it requires a cus_-prefixed customer_id, fetches all customer jobs and invoices, and warns that high-volume customers may cause a multi-second delay. This helps the agent set expectations and avoid surprises.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with labeled sections: outcome, USE WHEN, DO NOT USE WHEN, and GOTCHAS. It front-loads the core purpose, avoids repeating schema details, and every section contributes actionable information rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one simple parameter, an output schema, and annotations covering safety and idempotency, the description covers the remaining needed context: what the tool returns, when to use it, when not to use it, and practical gotchas. Nothing critical is missing for correct invocation and tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has only one parameter with no description and 0% coverage, so the description must compensate. It does by specifying that customer_id must use the cus_ prefix and is required in practice, which is the essential semantic for the single parameter. It does not go further into format details, but for a simple string ID the guidance is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a specific analytical tool: it computes customer intelligence as 9 binary pattern flags across churn risk, payment health, value, and service patterns, and returns only the patterns that fire with explanations. This makes its purpose concrete and distinguishes it from simple customer lookup or listing siblings like hcp_get_customer and hcp_list_customers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit USE WHEN scenarios such as customer history review, churn risk assessment, account health checks, and pre-estimate reviews. It also gives explicit DO NOT USE WHEN guidance with named alternatives, which is the ideal tool-selection support for an agent.
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 indicate readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context beyond that: default last 30 days, regex-based job type classification with v7 taxonomy and multi-label support, and first-assigned-tech attribution with no splitting of multi-tech jobs. These are non-obvious caveats an agent needs to interpret results correctly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear section headers, front-loaded with a one-line summary, and every sentence adds value. USE WHEN, DO NOT USE WHEN, and GOTCHAS are compact and immediately actionable without filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only analytics tool with an output schema present, this description covers purpose, usage, exclusions, default behavior, caveats, and parameter semantics adequately. No critical information is missing for an agent to decide whether and how to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the parameter-documentation burden. It compensates partially: 'Default is last 30 days' explains the date range parameters, 'per-technician' implies employee_id, and the job type breakdown note relates to include_job_types. It does not explicitly document all parameters or date formats, but the meaning is largely recoverable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific resource and metrics: 'Per-technician performance metrics — revenue, job count, avg value, completion rate.' It clearly distinguishes itself from employee lookup and scheduling by naming what it is not, and the stated use cases align exactly with the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit USE WHEN scenarios and DO NOT USE WHEN exclusions with named alternatives: hcp_list_employees for employee details and hcp_update_job_schedule for scheduling. This gives an agent clear decision rules for selecting this tool versus siblings.
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:

[![msio-server MCP server](https://glama.ai/mcp/servers/brystal00/msio-server/badges/card.svg)](https://glama.ai/mcp/servers/brystal00/msio-server)

Score Badge

Copy to your README.md:

[![msio-server MCP server](https://glama.ai/mcp/servers/brystal00/msio-server/badges/score.svg)](https://glama.ai/mcp/servers/brystal00/msio-server)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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/brystal00/msio-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server