Heroku MCP server

Official

by heroku

Overview Schema Related Servers Score Discussions

TypeScript

Remote

Server Quality Checklist

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

Latest release: v1.0.0
Disambiguation4/5
Most tools have distinct purposes targeting specific resources and actions, such as create_app vs. get_app_info. However, some PostgreSQL tools like pg_ps and pg_outliers have overlapping monitoring functions that could cause confusion, though their descriptions help differentiate them.
Naming Consistency5/5
Tool names follow a highly consistent verb_noun or noun_verb pattern throughout, such as create_addon, list_addons, pg_backups, and ps_scale. All use snake_case uniformly, with clear prefixes like 'pg_' for PostgreSQL and 'ps_' for process-related tools, making the naming predictable and readable.
Tool Count3/5
With 33 tools, the count is high and may feel heavy for the Heroku domain, as it includes many specialized PostgreSQL tools that could be consolidated. While comprehensive, it borders on being overwhelming compared to typical well-scoped servers (3-15 tools), though it covers a broad range of operations.
Completeness5/5
The tool set provides complete CRUD and lifecycle coverage for Heroku's core domains, including apps, add-ons, PostgreSQL, pipelines, and processes. It handles creation, retrieval, updates, deletion, and management operations across all areas, with no obvious gaps that would cause agent failures.
Average 4/5 across 33 of 33 tools scored. Lowest: 3.2/5.
See the Tool Scores section below for per-tool breakdowns.
- 0 of 6 community issues answered or closed in the last 6 months
- No commit activity data available
- Last stable release on August 11, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
This repository is licensed under Apache 2.0.
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

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the tool helps 'identify opportunities for performance optimization' and 'track query statistics over time', which implies read-only analysis, but doesn't explicitly state whether it's safe (non-destructive) or has side effects. It doesn't disclose that the 'reset' parameter can modify database statistics (a behavioral trait), nor does it cover permissions, rate limits, or output format. For a tool with parameters that can reset data, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded: it starts with the core purpose ('Identify resource-intensive database operations'), then lists four specific use cases in a bullet-like format, and ends with a summary sentence. Every sentence adds value by clarifying when and why to use the tool. There's no redundant or vague language, though it could be slightly more structured (e.g., separating purpose from guidelines more clearly).
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 complexity (performance analysis with potential side effects via 'reset'), lack of annotations, and no output schema, the description is moderately complete. It covers the 'why' and high-level 'when' but misses critical behavioral details (e.g., that 'reset' modifies data, what the output looks like). For a tool with 5 parameters and no structured safety hints, it should do more to explain risks and results, leaving gaps in contextual understanding.
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 100%, so the schema already documents all five parameters thoroughly (e.g., 'app' for Heroku app name, 'reset' for resetting statistics). The description doesn't add any parameter-specific information beyond what's in the schema—it focuses on high-level use cases instead. With high schema coverage, the baseline is 3, as the description doesn't compensate with extra semantic context but doesn't detract either.
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's purpose: 'Identify resource-intensive database operations' and lists specific use cases (find slow queries, analyze performance patterns, optimize workload, track statistics). It distinguishes itself from sibling tools by focusing on database performance analysis rather than app management, deployment, or other pg_* operations like backups or maintenance. However, it doesn't explicitly differentiate from all pg_* tools (e.g., pg_locks, pg_ps) in the same domain.
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 provides implied usage guidelines by listing four scenarios when to use the tool (e.g., 'Find slow or expensive queries', 'Optimize database workload'). However, it doesn't explicitly state when NOT to use it or name alternatives among the many sibling tools (e.g., pg_locks for lock analysis, pg_ps for process listing, or get_app_logs for broader app monitoring). The guidance is helpful but lacks exclusion criteria or direct sibling comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but lacks critical behavioral details. It mentions what the tool helps with but doesn't disclose whether operations are read-only or mutating, what permissions are needed, rate limits, or error conditions. The description is insufficient for a tool with potential operational impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening statement followed by bullet-like usage scenarios. It's appropriately sized at two sentences, though the second sentence could be slightly more concise by eliminating redundancy like 'helps maintain database backup operations'.
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 backup management tool with no annotations and no output schema, the description provides reasonable context about what the tool does but lacks critical details about behavioral characteristics, return values, and error handling. It's minimally adequate but leaves significant gaps for operational understanding.
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 100%, so the schema already documents the single 'app' parameter. The description doesn't add any parameter-specific information beyond what's in the schema, maintaining the baseline score of 3 for adequate but not enhanced parameter documentation.
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's purpose as managing database backup operations and schedules, with specific verbs like 'view', 'monitor', 'track', and 'verify'. It distinguishes from siblings like pg_info or pg_maintenance by focusing on backups, though it doesn't explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage scenarios (viewing backups, monitoring schedules, tracking progress, verifying availability) that clearly indicate when to use this tool. However, it doesn't specify when NOT to use it or name alternatives among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'safe promotion' and implies mutation (promoting/deploying), but lacks details on permissions required, whether promotions are reversible, rate limits, error handling, or what the response looks like. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
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 appropriately sized and front-loaded: it starts with the core purpose, then lists usage scenarios in a bullet-like format, and ends with a summary sentence. Every sentence adds value without redundancy, making it efficient and well-structured.
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 complexity (mutation with 2 parameters), no annotations, and no output schema, the description is moderately complete. It covers purpose and usage well but lacks behavioral details like side effects, error cases, or return values. It compensates somewhat with clear guidelines but falls short of fully addressing the gaps in transparency and output expectations.
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 100%, so the schema already documents both parameters ('app' and 'to'). The description adds some context by mentioning 'promote applications through pipeline stages' and 'multi-app promotions,' which aligns with the parameters, but doesn't provide additional syntax, format details, or examples beyond what the schema provides. Baseline 3 is appropriate when schema does the heavy lifting.
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's purpose: 'Promote applications through pipeline stages' and 'handles safe promotion of apps between pipeline stages.' It uses specific verbs ('promote,' 'deploy,' 'manage,' 'coordinate') and identifies the resource ('applications,' 'apps'), but doesn't explicitly distinguish it from sibling tools like 'deploy_to_heroku' or 'pipelines_create' beyond the pipeline context.
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 explicit usage scenarios: 'Use this tool when you need to: 1) Deploy code to staging or production environments, 2) Manage staged releases, 3) Coordinate multi-app promotions, 4) Control deployment workflows.' This gives clear context for when to use it, though it doesn't explicitly state when NOT to use it or name alternatives among siblings like 'deploy_to_heroku' for direct deployment.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the return format ('Returns a list of add-on services with their basic information') and implies read-only behavior through the 'list' action. However, it doesn't mention potential limitations like rate limits, authentication requirements, or pagination behavior. The description adds some context but leaves gaps in behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with three sentences that each serve a purpose: stating the tool's purpose, providing usage guidance, and describing the return value. It's front-loaded with the core functionality. There's minimal waste, though the second sentence could potentially be integrated more smoothly.
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 simple listing tool with one parameter and no output schema, the description covers the basics: purpose, usage, and return format. However, with no annotations and no output schema, it could provide more context about authentication requirements, rate limits, or error conditions. The description is adequate but has clear gaps in completeness.
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 has 100% description coverage, with the single parameter 'json' fully documented in the schema. The description doesn't add any parameter information beyond what's already in the schema. According to the scoring rules, when schema_description_coverage is high (>80%), the baseline is 3 even with no param info in the description.
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's purpose: 'List available Heroku add-on services' with the verb 'list' and resource 'add-on services'. It distinguishes from some siblings like 'create_addon' or 'get_addon_info' by focusing on listing all available services rather than creating or getting specific ones. However, it doesn't explicitly differentiate from 'list_addon_plans' which might list plans for specific services.
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 explicit guidance: 'Use this tool when you need to view all available add-on services.' This clearly indicates when to use it. However, it doesn't specify when NOT to use it or mention alternatives like 'list_addon_plans' for different listing needs, which would be helpful for sibling differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While it mentions security compliance and maintaining secure access, it doesn't specify whether this tool performs read-only operations, mutations, or both. It doesn't disclose authentication requirements, rate limits, or potential destructive effects. The description is too vague about actual behavior beyond the high-level purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening statement followed by a numbered list of use cases and a concluding sentence. It's appropriately sized at three sentences, though the concluding sentence could be more specific. Every sentence contributes value without redundancy.
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 complexity of credential management (potentially involving mutations), no annotations, and no output schema, the description provides adequate purpose and usage context but lacks behavioral details. It covers what the tool does and when to use it, but doesn't explain what operations actually occur, what permissions are needed, or what the tool returns. For a security-related tool with no structured safety information, this is minimally adequate.
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 100%, so the schema already fully documents both parameters. The description adds no parameter-specific information beyond what's in the schema. According to scoring rules, when schema coverage is high (>80%), the baseline is 3 even with no param info in the description, which applies here.
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's purpose as managing database access credentials and security, listing four specific functions (view, configure, rotate, set up monitoring). It distinguishes itself from sibling tools like pg_info or pg_backups by focusing on credential management rather than database information or backups. However, it doesn't explicitly contrast with all sibling tools, keeping it at a 4 rather than 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidelines with a numbered list of four specific scenarios when to use this tool: view credentials, configure permissions, rotate credentials, and set up monitoring access. This gives clear context for when the tool is appropriate, though it doesn't specify when NOT to use it or name exact alternatives among siblings.
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?
With no annotations provided, the description carries full burden. It states the tool 'provides visibility' and is for monitoring/checking/viewing/tracking/planning, which implies a read-only operation. However, it doesn't explicitly state whether this requires specific permissions, whether it's safe to use, what format the output takes, or if there are rate limits. The behavioral disclosure is adequate but lacks depth for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose statement followed by bullet-like use cases. Every sentence adds value: the first establishes core functionality, the second provides specific usage scenarios, and the third reinforces the tool's value. It could be slightly more concise by combining some elements, but overall it's efficient 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?
Given no annotations and no output schema, the description provides adequate coverage for a monitoring tool. It explains what the tool does and when to use it, but lacks details about output format, error conditions, or behavioral constraints. For a tool with 2 parameters and 100% schema coverage, the description is complete enough but doesn't fully compensate for the lack of output schema and annotations.
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 100%, so the schema already fully documents both parameters. The description doesn't add any parameter-specific information beyond what's in the schema. It doesn't explain how 'app' and 'database' parameters relate to the maintenance monitoring functionality. Baseline 3 is appropriate when the schema does all the parameter documentation work.
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's purpose: 'Monitor database maintenance status and operations' with specific use cases listed (check windows, view activities, track progress, plan tasks). It distinguishes itself from siblings like maintenance_on/maintenance_off (which control maintenance) and pg_info (general database info). However, it doesn't explicitly contrast with all relevant siblings like pg_backups or pg_upgrade.
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 explicit guidance: 'Use this tool when you need to:' followed by four specific scenarios. This gives clear context for when to select this tool. However, it doesn't mention when NOT to use it or explicitly name alternatives like maintenance_on/maintenance_off for controlling maintenance state or pg_info for general database status.
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?
No annotations are provided, so the description carries the full burden. It indicates the tool is for viewing/checking/verifying/monitoring, which suggests a read-only operation, but doesn't explicitly state safety aspects like non-destructive behavior or permission requirements. The description adds some context about providing comprehensive information, but lacks details on rate limits, error handling, or output format, leaving gaps in behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with a clear purpose statement followed by bullet-point-like usage scenarios. It avoids redundancy and stays focused on essential information. However, the final sentence ('The tool provides comprehensive pipeline information and structure details') is somewhat repetitive of earlier points, slightly reducing conciseness.
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 no annotations and no output schema, the description provides a reasonable overview but lacks completeness. It covers the tool's purpose and usage well, but misses details on behavioral traits (e.g., read-only confirmation, error cases) and output specifics. For a tool with 2 parameters and moderate complexity, this leaves the agent with some uncertainty about full behavior.
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 100%, with clear parameter documentation in the schema (pipeline name and JSON output option). The description doesn't add any parameter-specific details beyond what the schema provides, such as explaining pipeline name formats or JSON usage scenarios. Baseline 3 is appropriate since the schema handles parameter semantics adequately.
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's purpose as displaying detailed pipeline configuration with specific functions like viewing stage configuration, checking connected applications, verifying settings, and monitoring status. It distinguishes from siblings like pipelines_create (creation) and pipelines_list (listing) by focusing on detailed information retrieval. However, it doesn't explicitly contrast with get_app_info or similar tools, keeping it at 4 rather than 5.
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 explicit usage scenarios (e.g., view stage configuration, check connected applications) that clarify when to use this tool. It implies usage for detailed pipeline inspection rather than creation (pipelines_create) or listing (pipelines_list), but lacks explicit exclusions or alternatives for overlapping functions like get_app_info, preventing a score of 5.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'flexible filtering options' and the three usage scenarios, which gives some behavioral context. However, it doesn't disclose important traits like whether this is a read-only operation, potential rate limits, authentication requirements, or what format/log volume to expect in responses. The description adds value but leaves significant behavioral gaps unaddressed.
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 efficiently structured with a clear purpose statement followed by three specific usage scenarios in a numbered list. Every sentence earns its place by providing distinct value: the first establishes the core function, and the three bullet points give actionable usage guidance. There's no wasted text or redundancy.
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 4 parameters with 100% schema coverage but no annotations and no output schema, the description provides adequate purpose and usage context. However, for a tool that likely returns potentially complex log data, the description doesn't address response format, pagination, or data volume considerations. The completeness is minimal viable - adequate but with clear gaps in behavioral transparency that would help an agent use the tool 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?
Schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description mentions filtering 'by dyno, process type, or source' which maps to three parameters, and implies the 'app' parameter through 'application logs.' However, it doesn't add meaningful semantic context beyond what's already in the parameter descriptions. The baseline of 3 is appropriate when the schema does the heavy lifting.
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's purpose as 'View application logs with flexible filtering options' which specifies the verb (view) and resource (application logs). It distinguishes from siblings like get_app_info or ps_list by focusing specifically on logs rather than general app information or process status. However, it doesn't explicitly contrast with potential log-related siblings that might not exist in this set.
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 explicit usage scenarios: 'when you need to: 1) Monitor application activity in real-time, 2) Debug issues by viewing recent logs, 3) Filter logs by dyno, process type, or source.' This gives clear context for when to use the tool. It doesn't mention when NOT to use it or name specific alternatives among the sibling tools, but the scenarios are sufficiently detailed for an agent to make appropriate decisions.
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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes the tool as providing 'detailed information', 'comprehensive insights', and covering configuration, status, metrics, utilization, health, and capacity, which implies a read-only, non-destructive operation. However, it lacks specifics on permissions required, rate limits, error conditions, or output format details, leaving gaps in behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, starting with the core purpose ('Display detailed information about Heroku PostgreSQL databases') followed by usage scenarios. Each sentence adds value by elaborating on use cases and insights. It could be slightly more concise by avoiding repetition (e.g., 'detailed' and 'comprehensive' are somewhat redundant), but overall it's efficient.
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 complexity (information display with 2 parameters) and the absence of annotations and output schema, the description is moderately complete. It covers the purpose and usage well but lacks details on behavioral aspects like error handling, permissions, or output structure. Without an output schema, the description should ideally hint at return values, which it does not, leaving room for improvement.
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 100%, with both parameters ('app' and 'database') well-documented in the schema. The description does not add any parameter-specific semantics beyond what the schema provides (e.g., it doesn't clarify parameter interactions or usage nuances). According to the rules, with high schema coverage, the baseline is 3 even without param info in the description.
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 tool's purpose with specific verbs ('display', 'view', 'monitor', 'check', 'assess') and resources ('Heroku PostgreSQL databases', 'database configuration and status', 'performance metrics', 'connection and resource utilization', 'database health and capacity'). It distinguishes itself from sibling tools like pg_backups, pg_credentials, pg_kill, etc., by focusing on comprehensive information display rather than backups, credentials, or management operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage scenarios (e.g., 'when you need to: 1) View comprehensive database configuration and status...'), which gives clear context for when to use this tool. However, it does not explicitly state when NOT to use it or name specific alternatives among sibling tools (e.g., get_app_info for app-level details or pg_ps for process-specific info), which prevents a perfect score.
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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'direct SQL access with support for file-based queries and credential management', which adds some context about capabilities, but it does not disclose critical behavioral traits such as whether queries are read-only or can modify data, potential risks of destructive operations, authentication requirements beyond credential management, or rate limits. The description provides basic operational context but leaves significant gaps for a tool with SQL execution capabilities.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, starting with the core purpose and followed by a bulleted list of use cases and additional features. Every sentence earns its place by clarifying usage, but it could be slightly more concise by integrating the list into a smoother narrative. Overall, it is efficient with minimal waste.
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 complexity of a SQL execution tool with no annotations and no output schema, the description is moderately complete. It covers the purpose and usage guidelines well but lacks details on behavioral traits like safety, error handling, or return values. For a tool that can perform potentially destructive operations, more context on risks and outcomes would improve completeness, making it adequate but with clear gaps.
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 100%, so the schema already documents all five parameters thoroughly (e.g., 'app' as the app to run against, 'command' as the SQL command). The description does not add meaning beyond what the schema provides, such as explaining parameter interactions or providing examples. With high schema coverage, the baseline score of 3 is appropriate, as the description does not compensate with additional semantic insights.
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 tool's purpose with specific verbs ('Execute SQL queries') and resources ('against Heroku PostgreSQL databases'), distinguishing it from sibling tools like pg_backups or pg_info which focus on backups or database information rather than direct SQL execution. It explicitly lists four use cases, making the purpose unambiguous and comprehensive.
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 for when to use this tool by listing four specific scenarios (e.g., 'Run SQL queries for database analysis', 'Make schema modifications'), but it does not explicitly state when not to use it or name alternatives among sibling tools like pg_backups for backup-related tasks or pg_info for database metadata. The guidance is helpful but lacks explicit exclusions or comparisons.
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?
No annotations are provided, so the description carries full burden. It mentions the tool 'handles dyno scaling with support for type-specific adjustments', which hints at mutation behavior, but lacks details on permissions, rate limits, or what happens to existing dynos. It partially discloses behavior but leaves gaps for a mutation 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?
The description is front-loaded with the core purpose, followed by bullet-like usage points, and ends with a summary sentence. Every sentence adds value without redundancy, making it efficient and well-structured.
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 no annotations and no output schema, the description covers purpose and usage well but lacks details on behavioral traits like error handling or return values. For a mutation tool with two parameters, it's adequate but has clear gaps in completeness.
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 100%, so the schema already documents both parameters. The description adds context by mentioning 'type-specific adjustments' and viewing current formation, which aligns with the dyno parameter's optional nature, but does not provide additional syntax or format details beyond the 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 clearly states the verb ('Scale and resize') and resource ('Heroku application dynos'), with specific actions like adjusting quantities, changing sizes, viewing details, and managing allocation. It distinguishes from siblings like ps_list (which likely lists dynos) and ps_restart (which restarts them).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage scenarios (e.g., adjusting dyno quantities, changing sizes, viewing details), but does not specify when NOT to use it or name alternatives among siblings. It implies usage context but lacks exclusions like 'use ps_list for just listing without scaling'.
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?
With no annotations provided, the description carries the full burden. It discloses that the tool handles name generation if not specified and returns the new app's details, which adds behavioral context. However, it doesn't mention authentication requirements, rate limits, or potential side effects like billing implications, leaving gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with two sentences: the first states the purpose and customizable settings, and the second covers usage scenarios and behavioral details. It's front-loaded with the core function, though the second sentence is a bit dense with four bullet-like points.
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 mutation tool with no annotations and no output schema, the description is moderately complete. It covers purpose, usage, and some behavior (auto-naming, returns details), but lacks information on error handling, permissions, or response format. Given the complexity, it should do more to compensate for missing structured data.
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 100%, so the schema already documents all parameters thoroughly. The description adds minimal value by listing the four customizable settings (name, region, team, private space) but doesn't provide additional semantics beyond what's in the schema descriptions. Baseline 3 is appropriate when schema does the heavy lifting.
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 ('Create') and resource ('new Heroku application'), specifies customizable settings, and distinguishes from siblings like 'rename_app' or 'transfer_app' by focusing on initial creation. It's specific about what the tool does without being tautological.
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 lists four scenarios when to use this tool: creating with a specific name, in a particular region, within a team, or in a private space. It provides clear context for usage without needing to mention alternatives, as the use cases are well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by explaining the three identifier types accepted (ID, name, attachment name) and their contextual requirements, plus the access requirements. However, it doesn't mention rate limits, error conditions, or what 'comprehensive information' actually includes in the response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the core purpose, followed by usage guidelines and parameter context. Every sentence adds value, though it could be slightly more concise by integrating the parameter context more seamlessly.
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 read-only tool with no annotations and no output schema, the description does a decent job explaining what the tool does and parameter usage. However, it lacks details about the response format (what 'comprehensive information' includes), which would be important given the absence of output schema. The parameter coverage is good, but behavioral context could be more 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?
Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds some value by summarizing the three identifier types and their usage contexts, but doesn't provide additional semantic meaning beyond what's already in the detailed schema descriptions. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get comprehensive information') and resource ('about a Heroku add-on'), and distinguishes it from siblings by specifying three specific use cases (view add-on details, check plan details and state, view billing information). This is more specific than generic 'get' operations like get_app_info.
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 explicit guidance on when to use this tool ('when you need to: 1) View add-on details, 2) Check plan details and state, 3) View billing information'), but doesn't explicitly state when NOT to use it or name specific alternatives among the sibling tools (like list_addons for listing vs. get_addon_info for detailed info).
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?
No annotations are provided, so the description carries the full burden. It mentions output format options (JSON vs. simplified text) and hints at enterprise management use, but lacks details on permissions, rate limits, pagination, or error handling. The description adds some behavioral context but does not fully compensate for the absence of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and structured with bullet-like scenarios, making it efficient. However, the last sentence ('Essential for enterprise space management') is somewhat redundant and could be omitted without losing clarity, slightly reducing conciseness.
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 no annotations and no output schema, the description covers the tool's purpose and usage well but lacks details on behavioral aspects like authentication needs, response structure, or error cases. For a read-only list tool with one parameter, it is adequate but has clear gaps in completeness.
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 100%, with the single parameter 'json' well-documented in the schema. The description adds value by explaining the semantic impact of the parameter (e.g., 'Supports JSON output for detailed metadata' and 'Essential for enterprise space management'), providing context beyond the schema's technical details.
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 resource 'Heroku Private Spaces available to the user', specifying what the tool does. It distinguishes from siblings like 'list_apps' or 'list_teams' by focusing on private spaces, which is a distinct resource type in Heroku's ecosystem.
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 explicit usage scenarios (e.g., view all private spaces, get space details, check compliance features, view capacity information), giving clear context for when to use this tool. However, it does not specify when not to use it or name alternatives among sibling tools, such as 'list_apps' for non-private resources.
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?
No annotations are provided, so the description carries the full burden. It discloses that the tool 'validates name availability and handles the rename process', which adds useful behavioral context beyond the basic 'rename' action. However, it doesn't mention potential side effects (e.g., downtime, URL changes), permissions required, or error handling, leaving some gaps for a mutation 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?
The description is efficiently structured into three sentences: purpose, usage guidelines, and parameter/behavioral notes. Every sentence adds value with zero waste, making it front-loaded and appropriately sized for the tool's complexity.
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 no annotations and no output schema, the description provides good purpose and usage guidance but lacks details on behavioral aspects like side effects, permissions, or return values. For a mutation tool with 2 parameters, it's adequate but has clear gaps in completeness.
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 100%, so the schema already fully documents both parameters. The description mentions 'Requires both current app name and desired new name', which aligns with the schema but doesn't add meaningful semantics beyond what's already in the parameter descriptions. Baseline 3 is appropriate when schema does the heavy lifting.
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 'rename' and the resource 'Heroku application', specifying it's for existing apps. It distinguishes from siblings like 'create_app' (for new apps) and 'transfer_app' (for ownership changes), making the purpose specific and differentiated.
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 states when to use this tool: 'when a user needs to: 1) Change an app's name, or 2) Resolve naming conflicts.' It provides clear use cases and distinguishes from alternatives by focusing on renaming rather than creating or transferring apps.
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?
No annotations are provided, so the description carries the full burden. It mentions the tool returns 'detailed app status and configuration' and output format options, but lacks details on permissions required, rate limits, error handling, or whether it's read-only (implied by 'Get' but not explicit). It adds some behavioral context but is incomplete for a tool with no 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 front-loaded with the core purpose, followed by a bulleted list of use cases and parameter/output details. Every sentence adds value with no redundancy, making it efficient and well-structured for quick comprehension.
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 no annotations and no output schema, the description provides good context on what the tool does, when to use it, and output behavior. However, it lacks explicit safety disclosures (e.g., read-only nature) and detailed return format examples, leaving some gaps for a tool with no structured metadata.
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 100%, so the schema already documents both parameters (app name and json format). The description mentions 'Accepts app name and optional JSON format' but doesn't add meaning beyond the schema's detailed descriptions. Baseline 3 is appropriate when schema does the heavy lifting.
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 'Get' and resource 'comprehensive information about a Heroku application,' with specific details about what information is included (configuration, dynos, add-ons, etc.). It distinguishes from siblings like get_app_logs (logs only) or list_apps (list of apps without details).
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 lists five use cases (e.g., 'View app configuration and settings,' 'Check dyno formation and scaling'), providing clear guidance on when to use this tool. It implicitly distinguishes from alternatives like get_app_logs for logs or list_apps for listing apps without details.
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?
With no annotations provided, the description carries full burden. It mentions the response format (JSON vs human-readable) and filtering behaviors, but lacks details on permissions needed, rate limits, pagination, or error handling. For a list tool with no annotations, this is adequate but leaves gaps in operational context.
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 efficiently structured with a clear opening sentence followed by three numbered use cases. Every sentence directly supports tool selection and usage, with zero wasted words or redundant 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 list tool with no output schema, the description adequately covers purpose, usage, and parameter semantics. It could be more complete by mentioning response structure or pagination, but given the tool's relative simplicity and excellent schema coverage, it provides sufficient context for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all three parameters. The description adds value by summarizing the filtering options (all add-ons, specific app, JSON format) but doesn't provide additional syntax or format details beyond what the schema already explains. Baseline 3 is appropriate when schema does the heavy lifting.
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 resource ('Heroku add-ons'), and distinguishes this tool from siblings like 'get_addon_info' by specifying it's for listing with filtering options rather than retrieving detailed info about a single add-on. The three specific use cases further clarify the 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 states when to use this tool with three numbered scenarios: viewing all add-ons, listing for a specific app, and getting detailed metadata. It implicitly distinguishes from 'get_addon_info' (which likely gets info for one add-on) and 'list_addon_plans' (which likely lists plans rather than add-ons).
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'controlled process termination with optional force mode,' which indicates destructive behavior and a safety mechanism. However, it lacks details on permissions required, potential side effects (e.g., data loss), or error handling. For a destructive tool with zero annotation coverage, this is a moderate gap.
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 efficiently structured with a clear purpose statement followed by bullet-point usage guidelines and a final sentence about behavioral traits. Every sentence adds value, with no redundant or vague language. It is appropriately sized and front-loaded with critical 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 destructive tool with no annotations and no output schema, the description does well by covering purpose, usage scenarios, and key behavioral aspects (controlled termination, force mode). However, it lacks details on return values or error conditions, which would be helpful given the tool's complexity. It is mostly complete but has minor gaps.
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 100%, so the schema already documents all four parameters thoroughly. The description does not add any parameter-specific information beyond what the schema provides (e.g., it doesn't explain pid format or force mode implications). The baseline score of 3 is appropriate when the schema does the heavy lifting.
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 specific action ('terminate specific database processes') and resource ('database processes'), distinguishing it from sibling tools like pg_ps (which lists processes) or pg_maintenance (which manages maintenance). It provides a precise verb+resource combination that is not tautological with the tool name.
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 lists four specific scenarios when to use this tool: '1) Stop problematic or stuck queries, 2) Clear blocking transactions, 3) Manage resource-intensive operations, 4) Handle runaway processes safely.' This provides clear context and distinguishes it from alternatives like ps_restart (which restarts dynos) or maintenance_on/off (which controls app maintenance).
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the tool helps 'diagnose and resolve' problems, implying both read and potential action capabilities, but doesn't specify if it's purely diagnostic or can take corrective actions. It doesn't address permissions, rate limits, or what specific output format to expect.
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 efficiently structured with a clear purpose statement followed by a bulleted list of use cases and a concluding sentence. Every sentence adds value with no redundant information. The front-loaded structure immediately communicates the tool's core function.
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 diagnostic tool with 3 parameters and 100% schema coverage but no output schema, the description provides strong purpose and usage guidance. However, without annotations or output schema, it could better specify what information is returned (e.g., lock types, transaction IDs, query snippets) and any behavioral constraints.
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 100%, so the schema already fully documents all three parameters. The description doesn't add any parameter-specific information beyond what's in the schema. The baseline score of 3 is appropriate when the schema does the heavy lifting for parameter documentation.
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 tool's purpose with specific verbs ('analyze', 'diagnose', 'resolve') and resources ('database locks', 'blocking transactions', 'concurrency problems'). It distinguishes itself from sibling tools by focusing on PostgreSQL lock analysis rather than general database operations or app management.
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 lists four specific scenarios when to use this tool: 1) identify blocked queries and lock chains, 2) investigate deadlock situations, 3) monitor transaction lock states, and 4) resolve blocking issues affecting performance. This provides clear guidance on when this tool is appropriate versus other database or monitoring tools.
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?
With no annotations provided, the description carries full burden. It discloses the tool provides 'detailed visibility' and 'optional verbose output' for additional details, which helps understand its behavior. However, it doesn't mention potential rate limits, authentication requirements, or whether this is a read-only operation (though 'monitor' implies non-destructive).
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 efficiently structured with a clear purpose statement followed by a bulleted list of use cases and a concluding sentence about capabilities. Every sentence adds value with zero wasted words, making it easy to parse and understand quickly.
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 monitoring tool with no annotations and no output schema, the description provides good context about what the tool does and when to use it. However, it doesn't describe the return format or what specific information is included in the output, which would be helpful given the lack of 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 100%, so the schema already fully documents all three parameters. The description mentions 'optional verbose output' which aligns with the 'verbose' parameter but doesn't add meaningful semantic context beyond what the schema provides. Baseline 3 is appropriate when schema does the heavy lifting.
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 tool's purpose with specific verbs ('monitor', 'view', 'track', 'identify', 'debug') and resources ('active database queries and processes'). It distinguishes from siblings like pg_kill (termination) and pg_info (static info) by focusing on real-time monitoring of executing queries.
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 lists four specific use cases when to use this tool: 1) View currently executing queries, 2) Track query progress and resource usage, 3) Identify long-running or blocked queries, and 4) Debug performance issues in real-time. This provides clear guidance on appropriate contexts for tool selection.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is a creation tool ('Create new Heroku deployment pipelines') and mentions it 'manages pipeline creation with optional team and initial app configuration,' which implies mutation capabilities. However, it doesn't disclose permission requirements, rate limits, or what happens when creating duplicate pipelines, leaving behavioral gaps.
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 efficiently structured with two sentences: the first states the purpose, the second provides usage guidelines and additional context. Every sentence earns its place with no wasted words, and the bullet-point style use cases are front-loaded for quick scanning.
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 creation tool with no annotations and no output schema, the description provides good contextual coverage. It clearly explains what the tool does and when to use it. However, it doesn't describe what the tool returns or potential error conditions, which would be helpful given the absence of 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 100%, so the schema already fully documents all four parameters. The description mentions 'optional team and initial app configuration,' which aligns with the schema but doesn't add meaningful semantic context beyond what's already in the structured fields. Baseline 3 is appropriate when schema does the heavy lifting.
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 specific action ('Create new Heroku deployment pipelines') and resource ('pipelines'), distinguishing it from sibling tools like create_app or deploy_to_heroku. It provides a precise verb+resource combination that leaves no ambiguity about what this tool does.
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 lists four specific use cases when to use this tool: 1) Set up new deployment workflows, 2) Create staged application environments, 3) Organize apps by development stages, 4) Configure team-based pipeline structures. This provides clear guidance on appropriate contexts for tool selection.
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?
With no annotations provided, the description carries the full burden. It discloses the tool's read-only nature ('View') and output format option ('optional JSON output format'), but lacks details on permissions, rate limits, pagination, or error handling. It adds some behavioral context but leaves gaps for a list operation.
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 core purpose, followed by a structured bullet-like list of use cases and a final sentence on output format. Every sentence adds value with zero waste, making it highly efficient for agent comprehension.
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 tool's low complexity (list operation, 1 parameter, 100% schema coverage, no output schema), the description is nearly complete. It covers purpose, usage, and output format, but lacks behavioral details like pagination or auth requirements. It's sufficient for basic use but could be enhanced with more operational context.
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 100% for the single parameter 'json', which is documented in the schema as 'Output in json format'. The description adds marginal value by mentioning 'optional JSON output format', reinforcing but not expanding beyond the schema. Baseline 3 is appropriate as the schema does the heavy lifting.
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 specific verb ('View') and resource ('available Heroku pipelines'), and distinguishes from siblings like 'pipelines_create' (creation) and 'pipelines_info' (detailed info) by focusing on listing/visibility. It explicitly lists four use cases that clarify the scope beyond just listing.
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 when-to-use guidance with four numbered scenarios (e.g., 'List accessible pipelines', 'Check pipeline ownership'), clearly differentiating from siblings like 'pipelines_info' (for detailed config) and 'list_apps' (for apps not pipelines). It directly addresses the agent's decision-making context.
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?
No annotations are provided, so the description carries the full burden. It mentions 'optional JSON output format', which adds useful context about output behavior. However, it lacks details on permissions needed, rate limits, error conditions, or pagination. For a read-only monitoring tool with no annotations, this is adequate but not comprehensive.
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 core purpose ('List and monitor Heroku application dynos'), followed by specific use cases and an output format note. Every sentence earns its place, with no wasted words, making it highly efficient and well-structured.
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 no annotations and no output schema, the description does well by specifying use cases and output format. However, it could improve by mentioning typical return values (e.g., dyno types, states) or error handling. For a 2-parameter read tool, it's mostly complete but has minor gaps.
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 100%, so the schema already documents both parameters (app name and JSON format flag). The description adds no additional parameter semantics beyond what's in the schema. Baseline 3 is appropriate when the schema does the heavy lifting.
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 monitor') and resource ('Heroku application dynos'), distinguishing it from sibling tools like list_apps (which lists apps) and ps_restart/ps_scale (which modify dynos). It specifies the exact scope: viewing running dynos, checking status/health, monitoring process states, and verifying configurations.
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 four use cases (e.g., 'View all running dynos for an app', 'Check dyno status and health'), making it clear when to use this tool. It distinguishes from siblings by focusing on dyno monitoring rather than app listing (list_apps) or dyno modification (ps_restart).
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the tool 'manages process restarts with flexible targeting options' which implies mutation/destructive behavior, but doesn't explicitly state whether this causes downtime, requires specific permissions, or has rate limits. The description adequately conveys the core action but lacks operational 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?
The description is efficiently structured with a clear opening statement followed by a numbered list of use cases and a summary sentence. Every sentence adds value, with no redundant information or unnecessary elaboration.
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 mutation tool with no annotations and no output schema, the description does a good job explaining what the tool does and when to use it. However, it lacks information about potential side effects (downtime, data loss), authentication requirements, or what the tool returns. Given the complexity of a restart operation, some additional behavioral context would be beneficial.
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 100%, so the schema already documents all three parameters thoroughly. The description adds minimal value beyond the schema by mentioning 'flexible targeting options' and listing the four restart scenarios, but doesn't provide additional parameter semantics or usage examples beyond what's in the 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 clearly states the specific action ('Restart Heroku application processes') and resource ('dynos'), distinguishing it from sibling tools like ps_list (list processes) and ps_scale (scale processes). It provides a comprehensive overview of what the tool does beyond just the name.
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 lists four specific use cases when to use this tool (restart specific dynos, restart all dynos of a process type, full application restarts, reset dyno states selectively), providing clear guidance on its intended applications without needing to reference alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the provisioning process, automatic config var setting, and return of new add-on details. However, it lacks information on permissions, rate limits, or error conditions, which would be valuable for a creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose statement followed by bullet-point usage guidelines. Every sentence adds value, though the bullet points could be integrated more smoothly into prose. It's appropriately sized for a tool with four parameters.
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 creation tool with no annotations and no output schema, the description does a good job covering purpose, usage, and high-level behavior. It could improve by detailing error cases or response format, but given the rich parameter schema, it's mostly complete for agent use.
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 100%, so the schema already documents all four parameters thoroughly. The description adds minimal value beyond the schema, only mentioning parameters in the usage guidelines without providing additional semantics. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('create'), resource ('Heroku add-on'), and target ('for an application'), making the purpose specific. It distinguishes this tool from siblings like 'list_addons' or 'get_addon_info' by focusing on provisioning new resources rather than querying existing ones.
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 lists three scenarios for when to use this tool: provisioning a new add-on, specifying service/plan, and setting custom names. It also references sibling tools ('list_addon_services' and 'list_addon_plans') for discovering options, providing clear alternatives and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well by disclosing key behavioral traits: it 'replaces manual git push workflows,' 'handles app creation, source code deployment, and environment setup,' and specifies requirements like 'Requires valid app.json in workspace or provided via configuration.' It mentions support for 'team deployments, private spaces, and custom environment variables,' but lacks details on error handling, rate limits, or authentication needs, keeping it from a perfect score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, starting with the core purpose and key use cases. However, the last sentence about apps_list is slightly redundant with parameter descriptions in the schema, and some phrasing could be tighter (e.g., 'Use this tool when you need to:' list is verbose). Overall, it's efficient with minimal waste.
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 tool's complexity (8 parameters, no output schema, no annotations), the description is fairly complete. It covers purpose, usage scenarios, behavioral context, and references to sibling tools. However, it lacks details on output format, error cases, or authentication requirements, which would enhance completeness for such a multifaceted deployment tool.
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 100%, so the schema already documents all parameters thoroughly. The description adds minimal parameter semantics beyond the schema, such as implying app.json usage and referencing sibling tools for parameter values (e.g., apps_list for app name). This meets the baseline of 3, as the schema does the heavy lifting without significant added value from the description.
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 tool's purpose with specific verbs and resources: 'Deploy projects to Heroku, replaces manual git push workflows' and 'handles app creation, source code deployment, and environment setup.' It distinguishes from siblings by focusing on deployment rather than listing, creating, or managing resources like create_app or list_apps.
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 usage scenarios: 'Use this tool when you need to: 1) Deploy a new application..., 2) Update an existing application..., 3) Configure team or private space deployments, or 4) Set up environment-specific configurations.' It also references sibling tools (apps_list, spaces_list, teams_list) for prerequisites, offering clear alternatives and context.
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?
No annotations are provided, so the description carries the full burden. It mentions 'handles service restoration and process resumption' which adds some behavioral context beyond the basic action, but doesn't specify authentication requirements, error conditions, or what 'restoration' entails in detail. It adequately describes the mutation effect but lacks depth on implementation specifics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening statement followed by a bulleted list of use cases and a summary sentence. Every sentence adds value, though the final sentence slightly repeats earlier points. It's appropriately sized for the tool's complexity without unnecessary elaboration.
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 mutation tool with no annotations or output schema, the description provides good context: clear purpose, usage guidelines, and behavioral hints. It covers the essential 'what' and 'when' but lacks details on error handling or return values. Given the tool's simplicity, this is nearly complete, missing only minor operational specifics.
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 description coverage is 100%, fully documenting the single 'app' parameter. The description doesn't add any parameter-specific information beyond what's in the schema, but with only one well-documented parameter and no complex inputs, this is sufficient. A baseline of 3 is appropriate, but the simplicity elevates it to 4 as no additional clarification is needed.
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 specific action ('Disable maintenance mode') and resource ('Heroku applications'), distinguishing it from its sibling 'maintenance_on'. It uses precise language about restoring traffic routing and resuming dyno operations, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists four specific scenarios for when to use this tool: restoring traffic routing, resuming dyno operations, completing deployments, and verifying health after maintenance. It distinguishes from 'maintenance_on' by focusing on disabling rather than enabling maintenance mode, providing clear context for 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively communicates that this is a 'potentially destructive operation' (mentioned in the input schema description for 'confirm' parameter) and that it includes 'confirmation protection' and 'manages safe database version upgrades.' This covers key behavioral aspects like safety mechanisms and destructive potential.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with a clear opening statement followed by a bulleted list of use cases and a concluding sentence about safety features. Every sentence adds value, though the concluding sentence could be slightly more concise by integrating with the opening statement.
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 complex, potentially destructive database upgrade tool with no annotations and no output schema, the description provides good context about use cases and safety mechanisms. However, it doesn't mention what happens during the upgrade (downtime, backup requirements) or what the tool returns, leaving some gaps in completeness.
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 100%, so the schema already documents all four parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema descriptions, so it meets the baseline of 3 where the schema does the heavy lifting for parameter documentation.
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 specific action ('upgrade PostgreSQL database version') and resource ('PostgreSQL database'), distinguishing it from sibling tools like pg_backups, pg_info, or pg_maintenance which have different purposes. It goes beyond just restating the name by specifying the scope of the upgrade operation.
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 lists four specific use cases when to use this tool: 1) Migrate to newer version, 2) Plan upgrade paths, 3) Execute controlled migrations, and 4) Verify compatibility. This provides clear guidance on when this tool is appropriate versus alternatives like pg_maintenance or other database 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?
With no annotations provided, the description carries the full burden. It discloses key behavioral traits: it requires an 'add-on service slug' (authentication/input requirement), returns 'detailed plan information' (output behavior), and implies it's a read-only operation (no destructive hints). However, it doesn't mention rate limits, error conditions, or pagination, leaving some gaps.
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 core purpose, followed by specific use cases and requirements in a bullet-like format. Every sentence earns its place with no redundancy or fluff, making it highly efficient and readable.
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 tool's moderate complexity (2 parameters, no output schema, no annotations), the description is mostly complete. It covers purpose, usage, and key behaviors, but lacks details on output format variations (implied by the 'json' parameter) and error handling. With no output schema, more guidance on return values would be beneficial.
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 100%, so the schema already fully documents both parameters. The description adds minimal value beyond the schema—it mentions the 'service' parameter requirement but doesn't provide additional context like examples or edge cases. Baseline 3 is appropriate when the schema does the heavy lifting.
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 resource ('available plans for a specific Heroku add-on service'), distinguishing it from siblings like 'list_addon_services' (which lists services) and 'get_addon_info' (which gets info about a specific add-on). It specifies the exact scope of listing plans for a service.
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 three use cases (view all plans, compare pricing, check availability) and states when to use it ('when you need to...'), with no misleading guidance. It doesn't mention alternatives, but given the sibling tools, this is appropriate as no other tool directly lists plans.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by describing what the response includes ('app names, regions, and ownership information'), but doesn't mention pagination behavior, rate limits, authentication requirements, or error conditions. For a list tool with no annotations, this is good but not comprehensive.
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 and front-loaded with the core purpose, followed by specific usage scenarios and an alternative recommendation. Every sentence adds value, with no wasted words or redundant information. The three bullet-like scenarios are particularly effective.
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 list tool with no annotations and no output schema, the description does well by explaining what the response includes. However, it could be more complete by mentioning pagination behavior (if applicable) or typical response structure. Given the 5 parameters and lack of structured output documentation, it's good but not fully comprehensive.
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 description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description mentions 'flexible filtering options' which aligns with the schema, but doesn't add significant semantic value beyond what's already in the parameter descriptions. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('List') and resource ('Heroku applications'), and distinguishes it from sibling tools by mentioning 'flexible filtering options' and explicitly contrasting with get_app_info for checking app name availability. This provides clear differentiation from other tools in the server.
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 usage guidelines with three numbered scenarios for when to use this tool, plus a clear alternative ('prefer using get_app_info as it returns a more focused dataset'). This gives the agent specific guidance on when to choose this tool versus 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?
No annotations are provided, so the description carries the full burden. It discloses that the tool 'Supports JSON output for detailed team information' which adds useful behavioral context about output format options. However, it doesn't mention authentication requirements, rate limits, pagination behavior, or error conditions that would be important for a list operation.
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 efficiently structured with two sentences: the first states the core purpose, the second provides usage guidelines and output format information. Every sentence adds value, and the numbered list format for use cases is clear without being verbose.
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 operation with one optional parameter and no output schema, the description provides good context about what the tool does and when to use it. It could be more complete by mentioning authentication scope or whether it lists only active teams, but overall it gives sufficient guidance for agent selection and 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?
The schema description coverage is 100%, so the schema already fully documents the single parameter. The description adds value by explaining the practical implications of the 'json' parameter: 'returns a detailed JSON response containing team metadata such as enterprise account name' versus 'returns a simplified text format.' This provides semantic context beyond the schema's technical specification.
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 resource 'Heroku Teams the user belongs to', making the purpose specific and unambiguous. It distinguishes this tool from sibling tools like list_apps or list_addons by focusing specifically on team membership rather than other Heroku resources.
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 usage scenarios: 'when you need to: 1) View all accessible teams, 2) Check team membership, 3) Get team metadata and enterprise relationships, or 4) Verify team access for app operations.' These four specific use cases give clear guidance on when to select this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by explaining behavioral aspects: it 'manages traffic routing and process states while preserving running operations.' This reveals the tool's approach to handling existing operations during maintenance. However, it doesn't mention authentication requirements, rate limits, or potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with a clear opening statement followed by a numbered list of use cases and a concluding sentence about behavioral characteristics. Every sentence adds value with no wasted words, and information is front-loaded appropriately.
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 tool with no annotations and no output schema, the description provides good context about purpose, usage scenarios, and behavioral approach. However, it doesn't explain what the tool returns or what happens after maintenance mode is enabled, leaving some gaps in understanding the complete workflow.
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 100%, so the schema already documents the single 'app' parameter thoroughly. The description adds no additional parameter information beyond what's in the schema, meeting the baseline expectation when schema coverage is complete.
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 specific action ('Enable maintenance mode') and target resource ('Heroku applications'), distinguishing it from sibling tools like 'maintenance_off' which disables maintenance mode. It provides concrete functionality details rather than just restating the tool name.
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 lists four specific scenarios when to use this tool: redirecting traffic to a maintenance page, preparing for system updates/deployments, scheduling planned maintenance windows, and handling service interruptions. This gives clear context for when this tool is appropriate versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing permission requirements (owner or team admin), recipient requirements (must have Heroku account), and the ownership change nature. It doesn't mention potential side effects like billing changes or access revocation, but covers key behavioral aspects.
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 efficiently structured with three clear usage scenarios, parameter requirements, and permission prerequisites in three well-organized sentences. Every sentence adds value with no redundancy or wasted words.
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 mutation tool with no annotations and no output schema, the description provides good context about usage scenarios, permissions, and requirements. It could be more complete by mentioning potential side effects or confirmation of successful transfer, but covers the essential context well.
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 100%, providing complete parameter documentation. The description adds minimal value beyond the schema, only reinforcing the app ownership requirement and recipient account requirement already covered in schema descriptions. Baseline 3 is appropriate when schema does heavy lifting.
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 specific action ('transfer ownership') and resource ('Heroku application'), distinguishing it from sibling tools like create_app, rename_app, or get_app_info. It explicitly defines the tool's function beyond just the name.
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 usage scenarios (transfer to another user, move to a team, organizational changes) and prerequisites (current user must be app owner or team admin). It clearly indicates when to use this tool versus alternatives like create_app or rename_app.
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:

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

Score Badge

Copy to your README.md:

[![heroku-mcp-server MCP server](https://glama.ai/mcp/servers/heroku/heroku-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/heroku/heroku-mcp-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/heroku/heroku-mcp-server'

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