apex-mcp

Server Quality Checklist

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

Latest release: v0.4.0
Disambiguation2/5
Many tools overlap in purpose, especially the numerous metric/chart adders (add_metric_cards, add_kpi_row, add_ribbon_stats, add_stat_delta, add_spotlight_metric) and health/permission checkers (check_requirements, check_permissions, health_check). Agents will struggle to select the correct tool for a given intent.
Naming Consistency3/5
The predominant pattern is 'apex_verb_noun' in snake_case, but there are inconsistencies such as apex_status, apex_connect, apex_undo_last, and apex_dry_run_preview, which break the verb-object structure. Overall naming is readable but not perfectly consistent.
Tool Count1/5
With 120 tools, this is an extreme mismatch. Many tools are hyper-specific (e.g., separate adders for every chart type) and could be consolidated. The sheer volume overwhelms and makes selection impractical for an agent.
Completeness4/5
The tool surface is highly comprehensive, covering app lifecycle, page/component management, CRUD generation, analytics, REST endpoints, and more. However, there are minor gaps such as missing update/delete for LOVs, auth schemes, and some application-level components, and several overlapping tools for similar visual output.
Average 3.5/5 across 100 of 120 tools scored. Lowest: 2.4/5.
See the Tool Scores section below for per-tool breakdowns.
This repository is archived. Archived repositories automatically receive an F maintenance tier.
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With all annotations set to false, the description carries the full burden of behavioral disclosure, but it only states 'Add' with no mention of side effects, permission requirements, idempotency, or impact on existing processes. It does not contradict 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 a single, front-loaded sentence that efficiently conveys the core action. However, it is arguably too terse for an 11-parameter tool with multiple process types, but it remains concise and ordered.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters, multiple process types, page context), the one-sentence description is inadequate. It does not mention the need for page_id, how process_type interacts with other fields, or any return/result behavior. This is a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description's high-level summary ('PL/SQL block, DML on table, or branch redirect') is partially inaccurate and omits process types like 'ajax', 'close_dialog', and 'clear_cache'. It fails to add value beyond the schema and potentially misleads.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as adding a page process, but the listed process types ('PL/SQL block, DML on table, or branch redirect') are incomplete and include 'branch redirect' which is not among the schema's process_type enum values (dml, plsql, ajax, close_dialog, clear_cache). This introduces ambiguity about what the tool actually supports.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like apex_add_app_process. It does not specify that it operates on a specific page, nor does it mention any prerequisites or exclusions.
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?
The description only states 'Add an icon list' without disclosing that it likely creates a region on a page, requires a SQL query, or has any side effects. Annotations provide no helpful hints (all false), so the description carries the burden but fails to explain the operational behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very brief, which is generally good, but it omits essential information about the tool's operation. It is compact but under-specified, failing to earn its place by conveying only a minimal idea of the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 parameters, 3 required, and a core SQL query input, the description is inadequate. It does not explain how the SQL query drives the icon list, what the optional columns do, or how the agent should populate fields correctly. An output schema exists, but that does not compensate for the lack of usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (90%), but the description misrepresents the parameter structure by mentioning 'description' which is not a schema property, and by suggesting items are defined as {icon, label, description, page_id} when the schema uses label_column, value_column, and icon_column. This adds confusion rather than clarifying how to set the required sql_query.
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 uses the verb 'Add' with the resource 'icon list', indicating a specific action. However, it does not differentiate from sibling tools like apex_add_quick_links or apex_add_metric_cards, and the phrase 'Each: {icon, label, description, page_id}' is confusing because page_id is a top-level parameter, not an item property.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus other add_* tools. No context is provided about appropriate use cases, prerequisites, or alternatives, leaving the agent without decision support.
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 indicating read-only or destructive behavior, the description bears the full burden. It only states 'Add a ranked leaderboard table' without detailing side effects, required permissions, or what changes are made to the page. The SQL alias requirement is a technical constraint, not transparency about behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences), which is concise. However, the second sentence is cryptic and not fully informative, sacrificing clarity for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters and an output schema, the description is too sparse. It omits context such as how the leaderboard integrates with the page, what the output looks like, or any prerequisites (e.g., existing page_id). The schema partially fills this gap, but the description itself is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While schema coverage is 100%, the description's alias requirement ('RANK, NAME, VALUE') conflicts with the schema's label_column default 'LABEL' and the sql_query example using LABEL and VALUE. This creates confusion rather than adding meaningful parameter clarification.
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 'Add a ranked leaderboard table', specifying a distinct verb and resource. This differentiates it from sibling tools like apex_add_region or apex_add_metric_cards. However, the second sentence about SQL aliases introduces ambiguity and does not fully align with the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a constraint ('SQL must alias RANK, NAME, VALUE') but gives no guidance on when to use this tool versus alternatives. There is no mention of appropriate scenarios, prerequisites, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-idempotent write operation. The description adds no behavioral context beyond that—it does not mention side effects on the page, constraints, or what happens to existing content. The shorthand '{label, sql, color}' actually conflicts with the schema and adds confusion.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short, but the second sentence is an incomplete fragment that is not precisely accurate. It is concise in length but not optimally structured due to the misleading shorthand.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool that adds charts to a page, the description lacks critical context such as the target page_id, the 1–6 chart limit, and any side effects. The presence of an output schema does not compensate for the missing operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all parameters. The tool description adds no value and even introduces misleading shorthand that contradicts the schema's detailed chart fields (region_name, chart_type, sql, etc.).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add') and the resource ('a row of mini sparkline charts'), giving a specific verb+object. However, it does not differentiate from sibling tools like apex_add_sparkline or other chart-related tools, so it lacks sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no exclusions, and no mention of prerequisites. The description is a single terse line and provides no usage context.
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?
The annotations (readOnlyHint=false) already indicate this is a write operation, but the description adds little beyond that: it only restates 'Add a new page' with no details on side effects, required permissions, or impact on the app. The 'page_mode' mention is unhelpful and potentially misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded with the action, which is good for conciseness. However, the 'page_mode: Normal or Modal Dialog' phrase is unnecessary and somewhat off-target, making the sentence less effective than a wholly accurate one-liner would be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has six parameters, an output schema, and numerous sibling operations, this description is far too sparse. It does not explain how adding a page fits into the broader app-building workflow, nor does it highlight key options or constraints, leaving the agent under-informed for a complex write operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description introduces 'page_mode' which is not a schema parameter (the actual parameter is 'page_type'). This actively confuses rather than adds meaning, so I rate it below the baseline.
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 action ('Add a new page') and resource ('the app'), distinguishing it from sibling tools like apex_update_page and apex_delete_page. However, the mention of 'page_mode' is confusing because the schema uses 'page_type', which slightly detracts from clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. With many sibling tools for adding regions, items, or processes, such guidance is essential but entirely absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides no information about side effects, permissions, or what happens to existing page content. Annotations are all false, so the description carries the full burden, and it fails to mention that this tool modifies the page, potentially requiring a save/commit.
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?
At two short sentences, the description is very concise and front-loaded with the core purpose. However, it omits critical context, making it overly terse rather than appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 13 parameters with many optional settings (stacked, animation, zoom, scroll), the description is far too minimal. There is no mention of the update behavior, output structure, or relationships to other page elements.
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 description echoes the schema's requirement for series_list to contain SQL returning LABEL and VALUE columns. Since schema coverage is 100%, this adds minimal new meaning; it does highlight the core requirement but doesn't elaborate on any other parameters.
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 adds a filled area chart and specifies the required SQL columns (LABEL, VALUE). This makes the primary purpose explicit, though it does not distinguish it from sibling chart tools beyond the chart type implied by 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to choose this tool over other chart types (e.g., stacked chart, gauge, or scatter plot). The description lacks context about the use case or alternatives.
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?
Annotations are all false (not read-only, not idempotent, not destructive), which alerts the agent that this is a mutating operation, but the description itself adds no behavioral context. It does not mention what side effects occur (e.g., region creation), permissions needed, or return behavior.
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 a single concise sentence that front-loads the primary purpose. It is efficient, but the brevity sacrifices critical detail needed for a 19-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (19 parameters, 4 required, output schema present), the description is severely under-specified. It does not explain the relationship between bar_sql and line_sql, how to map columns, or any configuration caveats beyond the schema defaults.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema covers 100% of parameters, the description's SQL hint 'LABEL, BAR_VALUE, LINE_VALUE' is ambiguous and potentially contradictory with the schema's separate bar_sql and line_sql parameters. This can mislead an agent about how to structure the SQL queries.
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 adds a combo chart with bar and line on the same axes, which distinguishes it from other chart types among the many sibling chart tools. However, it does not explicitly call out alternatives or nuance beyond the basic definition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not explain when to choose this over other chart tools (e.g., area chart, stacked chart) nor any prerequisites or context for use.
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?
Annotations are all false, so the description carries the burden, but it only states a mutation ('Add') and does not disclose side effects, idempotency, or output behavior. With no extra context, the agent cannot anticipate if the operation replaces existing regions or how the query results are rendered.
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?
One sentence, front-loaded with the main action. It is appropriately succinct but the field list adds little value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 12 parameters, 3 required, and an output schema, this minimal description does not explain how the SQL query maps to columns, what the generated UI looks like, or any constraints (e.g., columns 2-4). For an AI agent to correctly invoke it, more guidance is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions, so baseline is 3. However, the description's field names 'body' and 'icon' conflict with schema fields (subtitle_column, badge_column), adding confusion rather than clarity. Therefore, it actually detracts from parameter understanding.
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 has a specific verb 'Add' and resource 'responsive grid of data cards', distinguishing it from sibling add_* tools. However, the field list {title, body, icon, badge} uses 'body' and 'icon' which do not correspond to actual schema parameters (subtitle_column, value_column, etc.), making it slightly misleading.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no context on when to use this tool versus alternatives like apex_add_metric_cards or apex_add_icon_list, nor any prerequisites or exclusions.
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?
Annotations indicate a mutating write operation (readOnlyHint=false), and the description merely restates 'Add'. No additional behavioral context (e.g., impact on page, reversibility, required permissions) is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but the dict format is terse and contains an error. It might have been clearer to reference the links array schema rather than an incomplete shorthand.
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?
While the schema and output schema provide structural details, the description lacks any high-level behavior context such as where the quick links appear (page/region) or how the grid is configured. The 'page_id' and 'region_name' are mentioned only in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides complete parameter descriptions (100% coverage), so the baseline is 3. However, the description's dict notation is inconsistent with the schema—listing 'page_id' instead of 'url' and omitting 'badge'—potentially misleading the agent.
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 identifies the action ('Add a grid of quick-link cards') and the resource type, distinguishing it from other add_* tools. However, the inline dict specification mentions 'page_id' while the schema defines 'url', creating minor ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool over alternatives such as apex_add_icon_list or apex_add_data_card_grid. There are no prerequisites or exclusions.
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?
Annotations indicate this is not read-only, but the description adds little beyond that. It does not disclose whether the target page ID must not already exist, whether associated regions/items are deep-copied, or what happens on conflict. The 'within the same app' claim contradicts the schema's allowance for cross-app copying, adding confusion rather than clarity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it includes a potentially incorrect qualifier ('within the same app') and omits important behavioral context. Every word should add value; the 'same app' phrase actively detracts. It could be clearer and more accurate without being much longer.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a copy operation with five parameters and an output schema, this description is incomplete. It does not explain the copy semantics (e.g., whether it is a deep copy, if target_page_id must be unused, or if related components are duplicated). The output schema may cover return values, but the operational behavior is under-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all parameters (100% coverage), including the optional new_page_name and target_app_id. The description itself adds no parameter-specific details and even misleads by implying same-app only. Thus it meets the baseline but does not enhance schema semantics.
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 a specific action ('Copy') and resource ('page'), with a destination ('new page ID'). It is distinguishable from sibling tools like apex_add_page or apex_update_page. However, it claims 'within the same app' while the input schema allows target_app_id to differ from source_app_id, which is misleading.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives (e.g., apex_add_page for new pages, apex_export_page for extraction). It does not mention prerequisites or scenarios where copying is preferred. Usage is only implied by the name and description.
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?
The description only states the action ('Add') without revealing side effects, ordering implications, or reversibility. Annotations indicate readOnly=false and idempotent=false, but the description adds no further behavioral context such as whether repeated calls create duplicates.
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 one sentence and front-loaded with the main action. However, the parenthetical list is cryptic and could be expanded or removed, though it does not add unnecessary length.
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?
While the schema and output schema are rich, the description is quite minimal for a complex tool with multiple computation types and execution timing options. The schema covers parameter semantics, but the description does not provide high-level guidance on how computations fit into page processing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides thorough descriptions for all 7 parameters, including the distinct computation types and execution points. The description does not add parameter details, but the baseline is satisfied by the high schema coverage.
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 function as adding a computation to set an item's value, which distinguishes it from related tools like apex_add_item or apex_add_process. The parenthetical mention of computation types ('STATIC, SQL, PL/SQL, ITEM') provides a useful overview, though it is somewhat abbreviated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool versus alternatives. The description does not mention common use cases, prerequisites, or why one would choose a computation over other mechanisms.
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?
Annotations are all false, indicating a mutation but not destructive. The description adds little behavioral context beyond 'add' – no mention of region creation, page impact, or side effects. With many similar tools, this lack of transparency makes selection harder.
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 a single sentence that efficiently conveys the core function. It is concise and front-loaded, but so brief that it omits differentiation and usage context, though the schema carries much of the detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 params) and a large sibling family, the description is too sparse to provide complete context. It relies heavily on the schema and does not explain when to choose this over related components like apex_add_kpi_row.
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 86%, so the schema already documents most parameters. The description merely restates that each metric includes label, sql, icon, and color, which is already in the schema, adding marginal value.
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 uses a clear verb ('Add') and resource ('styled KPI metric cards'), and specifies key attributes (gradient/flat/outline, label+sql+icon+color). However, it does not explicitly distinguish from sibling tools like apex_add_kpi_row or apex_add_spotlight_metric, so it loses a point.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, which is problematic given the many add_* siblings. It does not mention use cases, prerequisites, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provide behavioral hints, and the description only states an obvious add operation. It does not disclose whether the code replaces existing page JS, is appended, any side effects, or whether it is safe to re-run. The schema mention of a hidden static region is not in the tool description.
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 a single, clear sentence that immediately states the action and scope. It is front-loaded with the essential purpose and contains no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the schema is thorough and an output schema exists, the tool description is too minimal for a mutating operation with no annotations. It does not explain the effect on existing page scripts, whether the tool can be undone, or how it relates to sibling tools like apex_add_global_js. More context is needed for a tool that modifies a page.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with clear descriptions and examples for each parameter, especially javascript_code and js_file_urls. The tool description itself adds no extra semantic value beyond what the schema already provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (add) and resource (inline JavaScript) with a specific scope (a specific page). It distinguishes from the sibling tool apex_add_global_js by emphasizing page-specificity, though it does not mention the external JS file URL support, which is a minor incompleteness.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like apex_add_global_js for app-wide scripts or apex_add_page_css for styles. It lacks any contextual direction or exclusions.
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?
All annotations are false, so the description must disclose behavioral traits. It only says 'Add' without addressing side effects, permission requirements, or what happens if the region already exists. The mention of 'max' in the description but not in the schema creates confusion about behavior.
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 a single concise sentence, but the 'Each: {label, value, max, color}' phrase is cryptic and not a clear list of actual parameters. It is brief but slightly opaque, earning a 4 rather than a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 9 parameters and an output schema, the description is severely underspecified. It lacks usage scenarios, prerequisites, and a clear data contract for the SQL query. The output schema covers return values, but the description fails to tie the input parameters to the visual output, especially the 'max' concept.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While schema coverage is high (89%), the description adds a 'max' field that has no corresponding schema property, which is misleading. It does not clarify how sql_query maps to label/value columns beyond the schema's own descriptions, and the structure '{label, value, max, color}' does not align with the actual parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Add horizontal percent bars' with a clear verb and resource, making the tool's action obvious. The 'Each: {label, value, max, color}' snippet further clarifies the bar structure, and the name itself distinguishes it from sibling chart tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like apex_add_jet_chart or apex_add_metric_cards. There are no prerequisites, exclusions, or contextual hints for selecting percent bars.
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?
Annotations are all false, providing no safety/behavioral signal. The description adds little beyond the fact that it 'adds' a metric, failing to disclose that it likely executes the provided SQL query and modifies the page. No side effects, permissions, or dependencies are mentioned.
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 a single, front-loaded sentence with no filler. It is concise and to the point, though it sacrifices informative detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 13 parameters and 4 required, this is a complex tool. The description provides no context about how the metric appears on the page, what the SQL query should return, or how it integrates with regions. The minimal phrasing is inadequate for the tool's complexity.
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 baseline is 3. The description loosely maps 'value', 'label', and 'optional trend' to params like sql_query, label, and subtitle_sql, but adds no meaning beyond what the schema already provides.
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 uses a clear verb ('Add') and specific resource ('large spotlight metric'), mentioning key components (value, label, optional trend). It distinguishes this from generic 'add' tools, but not from closely related sibling tools like apex_add_metric_cards or apex_add_gauge, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as apex_add_metric_cards, apex_add_gauge, or apex_add_stat_delta. There are no exclusions or context cues, leaving the agent to infer usage from the name alone.
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?
Annotations are all false, offering little behavioral context. The description only says 'Add' without disclosing whether this creates a new region, modifies the existing region, replaces series, or requires specific permissions. It adds no meaningful behavioral information beyond the action itself.
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 extremely short and front-loaded with the main action. The 'SQL: LABEL, VALUE, SERIES' fragment is terse but not wasteful. However, it is cryptic enough that it doesn't fully stand alone without the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 13 parameters and an output schema not shown in the input, the description is too sparse to give an agent a complete understanding. It doesn't explain how page_id, region_name, and series_list interact, nor the overall workflow of the tool. This is a significant gap for a complex 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?
The input schema has 100% coverage, with descriptions for every parameter, so the baseline is 3. The description's 'SQL: LABEL, VALUE, SERIES' adds a minor summary of the series_list structure but provides no new semantics beyond what the schema already describes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Add a stacked bar/column chart.' It uses a specific verb and resource, and the 'stacked' qualifier distinguishes it from other chart tools. However, it doesn't explicitly differentiate it from similar chart types like area or combo charts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention use cases, prerequisites, or exclusions. An agent comparing many chart-addition tools gets no help in deciding if a stacked chart is the right choice.
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?
The annotations are all false, so they provide no positive safety signals. The description merely says 'Add' without disclosing side effects, page modification behavior, or dependencies. It adds little beyond the obvious mutation implied by the name.
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 a single concise, front-loaded sentence with no wasted words. It is appropriately short, though it could be slightly more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a tool with six parameters, a complex array structure, and an output schema, the one-sentence description is insufficient. It does not mention prerequisites like an existing page, how the tabs container integrates with APEX regions, or any constraints not already in the schema. The schema covers parameter details, but the overall tool behavior remains under-specified.
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 high (83%), and the tabs parameter has a detailed description of its sub-fields. The tool description itself adds no extra parameter semantics beyond the schema, so the baseline score of 3 applies.
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 uses a specific verb and resource ('Add a tabs container with multiple content panels'), clearly indicating the tool's purpose. It does not, however, explicitly mention the Oracle APEX page context or differentiate from sibling region-adding tools, though the name provides some distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like apex_add_region or apex_add_collapsible_region. The description only restates the function without providing context, prerequisites, or exclusions.
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?
Annotations are all false, providing no meaningful hints about safety or side effects. The description does not disclose what happens on the page, whether it can be called multiple times, or if any prerequisites exist. For a mutation tool, this lack of transparency leaves the agent uninformed about behavioral outcomes.
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 a single, front-loaded sentence with no fluff. It quickly conveys the core action. The parenthetical 'TAG + WEIGHT columns' is terse but does not derail the structure, though it is conceptually imprecise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters and no useful annotations, the description is too brief. It does not explain the expected SQL format, the relationship between sql_query and label/count columns, or the default behavior of optional parameters. The full schema coverage helps, but the description itself lacks contextual depth needed for correct usage.
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 descriptions cover 100% of parameters, so the baseline is 3. The description adds no meaningful extra parameter semantics and introduces 'TAG + WEIGHT' which conflicts with the schema's label_column/count_column terminology, slightly undermining clarity. Still, the schema itself is thorough, so the description is not misleading enough to drop below baseline.
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 adds a tag/word cloud and specifies the data source (SQL). It uses a specific verb 'Add' and resource 'tag/word cloud', which distinguishes it from many sibling add_* tools. However, the phrase 'TAG + WEIGHT columns' is slightly ambiguous given the schema uses label_column/count_column, creating minor confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as apex_add_jet_chart or other visualization tools. The description only states what it does, leaving the agent to infer usage solely from the tool name.
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?
Annotations indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false, but the description adds little beyond the word 'update'. It doesn't disclose potential side effects, whether changes are reversible, or what happens if the region or app doesn't exist. Given minimal annotation coverage, the description should provide more context but doesn't.
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 a single concise sentence with no wasted words. It is front-loaded with the primary verb and resource. However, it could be slightly more informative by listing all key updateable fields without becoming overly long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 10 parameters, 3 required, and many sibling update/add/delete tools, the description is too sparse to provide enough context for correct selection. It doesn't explain the full range of updates, prerequisites, or how it fits into the broader workflow. The output schema exists but doesn't compensate for the lack of usage and behavioral guidance.
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 each of the 10 parameters having its own description. The tool description itself doesn't add meaning beyond the schema, such as explaining which parameters are mutually exclusive or how condition type/expression are related, so the baseline of 3 applies.
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 updates a region's SQL source, title, or template, which identifies the verb and resource. However, it only names a subset of the actual updateable fields (e.g., omits sequence, auth scheme, conditions, static content), so it doesn't fully capture the tool's scope or clearly distinguish it from sibling update tools like apex_update_item or apex_update_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives such as apex_add_region or apex_update_page. It only implies usage for updating an existing region, without any exclusions, prerequisites, or reference to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly supports DML/DDL statements, which can modify data and schema, yet the annotations declare readOnlyHint=true and destructiveHint=false. This is a direct contradiction. The description also provides no warnings about potential side effects, commits, or irreversibility. This is a serious transparency failure.
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 a single, focused sentence that captures the core function (execute SQL) and the key output types (rows or affected count). There is no redundancy or filler, and the information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description omits critical context for a tool that can execute DML/DDL: no mention of transaction handling, the ability to undo changes, or the need for permissions. Given the tool's power and the contradictory annotations, the description is incomplete even though the schema provides parameter details.
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% coverage, with detailed descriptions and examples for sql, max_rows, and bind_params. The description adds no additional parameter semantics beyond the schema, but since the schema fully explains each parameter, the baseline score of 3 is appropriate.
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 executes any SQL statement (SELECT/DML/DDL) and returns rows or affected count. This is a specific verb-action (execute) on a clear resource (SQL) and distinguishes the tool from sibling APEX tools that focus on app building rather than raw SQL execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is given. The description does not indicate when to use this tool versus alternative, safer options like apex_describe_table or apex_generate_crud. There are no exclusions or prerequisites mentioned, leaving the agent without clear direction on when raw SQL execution is appropriate.
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?
The description adds a small behavioral detail ('counts up on page load'), but with all annotations false (readOnlyHint=false, etc.), the description carries the burden of explaining side effects, permissions, or page modifications. It only says 'Add' without clarifying what changes are made or what the result means, providing minimal transparency beyond that single behavior.
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 a single, clear sentence with no fluff or redundancy. It front-loads the core action ('Add an animated counting number with label') and appends the relevant behavior. Every word earns its place, making it appropriately concise for a tool of moderate 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?
The tool has 14 parameters, an output schema, and a rich set of sibling tools, but the description is quite sparse. The schema covers parameter details well, and the output schema reduces the need to explain return values. However, the description lacks usage context and behavioral expectations (e.g., how the counter integrates with a page/region), making it minimally complete but not fully adequate for an agent to select this over similar dashboard widgets confidently.
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% (as indicated by context signals), so every parameter is fully described in the schema. The description adds no parameter-specific meaning beyond what the schema already provides. Per the rubric, a high coverage baseline gives a score of 3, and there is no additional value to push it higher.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: "Add an animated counting number with label" and adds a key behavior "counts up on page load." This clearly conveys what the tool does and implicitly distinguishes it from other add_* tools, but it does not explicitly compare with siblings like apex_add_metric_cards or apex_add_stat_delta, so it does not fully earn a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to choose this tool over alternatives, no prerequisites, and no exclusions. It only says what the tool does, leaving the agent to infer usage entirely from the name and schema. This falls under 'no guidance' rather than implied usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false and do not convey a safety profile; the description at least reveals this is an additive mutation ('Add ... KPI cards') and mentions the card fields. However, it does not disclose behavioral details like whether an existing region is replaced, whether CSS/style blocks are modified, or any idempotency/reversibility concerns.
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 a single short sentence that front-loads the primary action and object. It contains no filler and is immediately understandable, making it highly concise.
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?
An output schema exists, so return values need not be explained, and the input schema covers most parameters. Still, the tool description has the icon/suffix mismatch, omits optional parameters, and gives no contextual guidance relative to other KPI/metric tools, leaving moderate gaps in fully understanding the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents most parameters, so the baseline is 3. However, the description lists 'icon' as a card key, while the schema's metric object documents 'label', 'sql', 'suffix', and 'color' but not 'icon'. This inconsistency may mislead the agent into constructing metrics incorrectly and reduces clarity.
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 uses a specific verb ('Add') and resources ('horizontal row of KPI cards'), with a compact structure hint. It is clear but does not explicitly distinguish itself from similar sibling tools like apex_add_metric_cards or apex_add_stat_delta.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description only restates the action and card format, implying usage from the tool name, but lacks any explicit exclusions or comparisons to sibling add_* 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?
The description says only 'Add a range chart' and gives SQL column hints, but it does not disclose behavioral traits such as page modification, region creation, or prerequisites (e.g., page must exist). Additionally, the description's SQL columns (LOW_VALUE, HIGH_VALUE) conflict with the schema's low_column/high_column defaults (LOW, HIGH), creating ambiguity about expected input.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence, front-loaded with the core purpose and the key SQL requirement. It contains no redundant information and is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 15 parameters, many sibling chart tools, and an output schema, the description is too sparse. It does not explain what a range chart is used for (beyond 'min-max bars'), does not mention how it integrates with APEX regions, and the column-name mismatch leaves the tool's distinct behavior underspecified. The schema and annotations cannot compensate for this contextual gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the baseline is 3. However, the description's SQL hint (LABEL, LOW_VALUE, HIGH_VALUE) does not match the schema's defaults (low_column default LOW, high_column default HIGH) and the example query in the schema uses LOW/HIGH. This inconsistency undermines the value of the description and could mislead parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Add a range chart (min-max bars)' with a specific verb (Add) and resource (range chart), and the SQL shape (LABEL, LOW_VALUE, HIGH_VALUE) further distinguishes it from other chart tools. This clearly differentiates it from sibling apex_add_* chart tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention use cases (e.g., showing min-max ranges over time) or distinguish when a range chart is preferred over other chart types. No alternatives are referenced.
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?
Annotations provide no safety signals (all false), so the description carries the full burden. It only says 'Add a region', which implies a mutation but does not disclose any side effects such as persistence, permission requirements, or consequences of adding a region with an existing name. For a write operation, this is a significant transparency gap.
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 a single sentence that is front-loaded with the primary action. It is concise and easy to parse. However, the types list is redundant with the schema and omits many valid types, so it does not fully earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters, many region types) and rich schema, the description is too brief. It does not explain the breadth of region types or provide guidance on when to use specific types, and the partial list could mislead an agent into thinking only those types exist. The output schema covers return values, so that is not a concern, but the overall context is inadequate.
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 baseline is 3 even without parameter info in the description. The description's list of types adds some context for the region_type parameter, but it is incomplete and slightly inaccurate, offering marginal value beyond the schema.
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 action: 'Add a region to a page.' This is a specific verb+resource+target that distinguishes it from sibling tools like apex_add_item or apex_add_page. However, the list of types ('STATIC, IR, PLSQL, chart, blank') is incomplete and includes 'blank', which does not appear in the schema's region_type enum, slightly muddying the clarity.
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 phrase 'Add a region' implies usage for creating regions, but there is no explicit guidance on when to use this tool versus alternatives like apex_update_region or apex_delete_region. It does not mention any exclusions or prerequisites, leaving usage largely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a mutation (readOnlyHint=false), and the description does not contradict this. The note about SQL columns adds a small operational detail about required data shape. However, it does not disclose side effects, prerequisites like page existence, or interactions with existing regions, so it adds only marginal 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 extremely concise, with two short sentences and no wasted words. It is front-loaded with the core action. However, it is so sparse that it borders on under-specification, which prevents a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 16 parameters and 3 required, the description is inadequate as a standalone overview. It does not describe the tool's role in the APEX page lifecycle, its effects on the page, or provide an example usage. The SQL hint is already present in the schema, so the description adds little beyond a one-line action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description's 'X_VALUE, Y_VALUE, optional LABEL' shorthand is a high-level echo of the sql_query parameter description, but it does not add syntax or value details beyond what parameters already provide. It neither significantly compensates nor hurts.
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 adds a scatter plot, which is a specific verb+resource. However, it does not explicitly differentiate from sibling chart tools beyond the chart type name. The SQL note hints at data requirements but does not add differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to choose a scatter plot over the many sibling chart tools (e.g., bubble chart, combo chart, jet chart). There is no mention of use cases, prerequisites, or alternatives. This is essentially no usage guidance beyond the tool name.
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?
The annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds no additional behavioral context such as side effects, failure modes (e.g., duplicate username), or permission requirements. It merely restates the create operation without enriching what the annotations already provide.
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 a single, front-loaded sentence that directly states the core action. The inclusion of the role list is unnecessary given the schema, making it slightly less concise than ideal, but it remains 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?
Since the input schema is fully described and an output schema exists, the description is not required to explain return values. However, it lacks important context such as the default behavior of workspace_id, how roles are determined, and any preconditions, leaving the overall picture incomplete for a create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for all six parameters, so the description's role mention is the only extra information. However, there is no 'role' parameter in the schema, which could mislead an agent into expecting a role argument. The description fails to clarify how roles are assigned and adds confusion rather than value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Create' and identifies the exact resource 'APEX workspace user', making the tool's purpose unmistakable. It also lists role options to clarify the intent, distinguishing it from siblings like apex_list_users or apex_check_permissions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, nor any mention of prerequisites or context such as needing an active workspace or admin permissions. The usage is only implied by the verb 'Create', leaving the agent to infer when it should be invoked.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate that this is not read-only and not destructive, so the description does not need to cover those basics. It adds value by listing some updatable attributes, but it does not disclose important behaviors like whether omitted parameters are left unchanged, whether new_lov_definition only applies to select lists, or whether changing the item type has cascading effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the verb and resource. It is not bloated, but it is so terse that it omits several updatable fields, making it less helpful than a slightly longer description would be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and annotations, the description lacks context for a complex tool with 11 parameters and 3 required fields. It does not explain how to locate an item (app/page/item_name), the behavior of null parameters, or constraints like new_lov_definition being for select lists only. This could lead an agent to misuse the 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?
The schema descriptions cover 100% of parameters, so the baseline is 3. The description's mention of LOV, label, type, and default adds little beyond what the schema already provides; it does not clarify the optional null semantics or how the new_* parameters interact with existing item settings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update) and the resource (an item in an existing app), distinguishing it from sibling tools like apex_add_item, apex_delete_item, and apex_update_region. It enumerates a few key properties (LOV, label, type, default), which gives a quick sense of the tool's scope, though it omits other fields like read-only, required, and placeholder.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives (e.g., apex_add_item, apex_update_region, or apex_describe_page). The description does not mention prerequisites, such as needing the app/page/item to exist, or when to use a different update approach.
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?
The description only says 'Add an activity/audit stream' and mentions SQL aliasing. It doesn't disclose side effects, permission needs, idempotency behavior, or what happens if requirements are not met. Annotations are all false, providing minimal safety profile, so the description carries the burden but adds little.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: a clear purpose statement and a critical SQL requirement. No fluff, every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 12 parameters and an output schema, the description provides almost no high-level context beyond the name and a single constraint. It doesn't explain what an activity/audit stream is, when to use it, or best practices for the SQL query. The schema provides parameter details but not 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 92%, so the schema already documents most parameters. The description adds value by specifying that SQL must alias TIMESTAMP, USER_NAME, ACTION, which is not in the schema. This slight extra meaning justifies a baseline 3 rather than lower.
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: 'Add an activity/audit stream.' This is a specific verb+resource that distinguishes it from sibling tools like apex_add_timeline or apex_add_region. The additional SQL alias requirement adds useful specific detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to choose this tool over alternatives. The only usage-related detail is the SQL alias requirement, which is a constraint rather than contextual guidance. It doesn't mention scenarios, prerequisites, or exclusions.
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?
Annotations already indicate a non-read-only operation (readOnlyHint=false), and the description's 'Add' is consistent. However, no extra behavioral context is provided beyond what annotations convey—no mention of side effects, prerequisites, or failure modes. The only added constraint is about SQL input, not tool behavior.
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?
Two concise sentences front-load the core purpose and a key constraint. No filler, but it could be slightly more informative without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 9 parameters and an output schema, but the description stays minimal. While the schema covers parameter details, the description does not address the broader context (e.g., when to prefer this over other region types, or what happens after creation). It is adequate but not 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?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description's note about date and title columns merely reinforces existing schema descriptions without adding new semantic meaning. Baseline of 3 applies.
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 that the tool adds a calendar region, which is a specific verb + resource. It distinguishes itself from sibling region-adding tools (e.g., apex_add_region, apex_add_timeline) by naming 'calendar' as the region type, though it does not explicitly contrast them.
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 requirement 'SQL must include a date column and a title column' implies when to use this tool (with data that has date/title fields), but there is no explicit guidance on alternatives or exclusions. Usage context is implied rather than stated clearly.
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?
Annotations are all false, providing no safety or idempotence hints, so the description must carry the transparency burden. The one-sentence description does not disclose side effects such as page mutation, dependency on existing regions, or failure behavior if prerequisites are unmet.
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 a single, front-loaded sentence that conveys the core action in a compact format. Every word is useful, with no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters and a non-trivial workflow, the description is too minimal. It doesn't mention that the chart and IR regions must already exist, the auto-prefixing of item names, or that this modifies page metadata. Although the schema fills some gaps, the description itself lacks enough context for an agent to know when and how to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 6 parameters with rich descriptions (e.g., target_item_name auto-prefix, filter_column informational), and description coverage is 100%. The main description adds no parameter-level meaning, so the baseline 3 is appropriate.
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 action ('Add chart drilldown') and the specific workflow (click chart series → set hidden item → refresh IR). This distinguishes it from sibling tools like apex_add_jet_chart or apex_add_dynamic_action by naming the drilldown behavior explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, exclusions, or alternative approaches. The only usage hints are in the schema descriptions for chart_region_name and target_region_name, which state the regions must already exist, but this is not in the main description.
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?
The description briefly notes the auto-prefix behavior, but this is already present in the item_name schema description. It does not disclose additional behavioral traits such as permission requirements, reversibility, or the fact that it mutates the APEX app. Annotations are all false, so they provide no positive safety context. No contradiction is present, but the description adds little beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence followed by a compact list of types. There is no redundancy or fluff, making it very efficient and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 13 parameters and a rich schema, the description is too sparse. It does not mention required parameters, prerequisite that the region must exist, or important constraints like 'select requires lov_name'. The output schema covers return values, but for a tool of this complexity, the description leaves out key contextual information.
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 detailed parameter descriptions, so the baseline is 3. The description adds minimal extra meaning; its type list is actually a subset of the schema's fuller enumeration, so it does not enhance parameter understanding 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 'Add a form item' with a specific verb and resource, and lists item types. This distinguishes it from sibling tools like apex_update_item, apex_delete_item, and apex_bulk_add_items, 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as apex_bulk_add_items or apex_update_item. It also omits prerequisites like the region must already exist (though the schema mentions this). This leaves the agent without explicit direction on tool selection.
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?
Annotations are all false, so they do not convey a safety profile (e.g., readOnlyHint=false, destructiveHint=false). The description fails to disclose that this is a mutating operation that modifies the APEX application by adding a chart region. No mention of permissions, side effects, or reversibility, leaving the agent unaware of the tool's impact.
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 a single sentence of 13 words, efficiently stating the core function and key SQL requirement. It is front-loaded, with no redundancy, filler, or unnecessary details, making it exemplarily concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 15 parameters, this one-sentence description is inadequate. It omits any mention of required page_id and region_name, the role of cumulative_sql, or the context of adding a chart within an APEX page. The description relies entirely on the schema for critical context, which is insufficient for an agent to fully understand the tool's operation.
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, so the baseline is 3. The description adds minimal extra meaning by stating 'SQL: LABEL, VALUE,' which aligns with the sql_query parameter's example. However, it does not further explain the columns' roles or options like cumulative_sql, so it stays at baseline.
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 'Add a Pareto chart (bars + cumulative % line).' This specifies the verb, resource, and unique distinguishing feature (cumulative % line) that separates it from sibling chart tools. The 'SQL: LABEL, VALUE' hint further clarifies the expected input format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like apex_add_combo_chart or apex_add_gauge. It does not mention that a Pareto chart is appropriate for analyzing frequencies in descending order, nor does it suggest any exclusions. The description simply states what it does without contextual placement.
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?
The description says nothing about behavioral side effects—whether it overwrites an existing page, creates a sample query if ir_sql is omitted, or what the resulting page looks like beyond 'KPI cards and charts.' Since annotations provide no positive hints (all flags false), the description carries the full burden and fails to disclose mutation details or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the core action and outcome. No filler or redundant phrasing. It earns its place as a concise summary, though it sacrifices some depth for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex generator with 5 parameters, an output schema, and many sibling tools, this description is too minimal. It omits important operational context like sample KPI card generation, default IR SQL behavior, and page overwrite semantics. The schema covers parameters but not the overall workflow or effects.
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% (all 5 parameters have meaningful descriptions, including defaults and the kpi_queries format). The tool description adds no parameter-specific information, but the schema already handles semantics effectively, so the baseline of 3 is warranted.
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?
Clearly states a specific action ('Generate') and resource ('dashboard page') with content details ('KPI metric cards and JET charts'). This distinguishes it from sibling tools like apex_add_metric_cards and apex_generate_report_page, which focus on individual components or other page types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this tool versus alternatives such as apex_generate_analytics_page or apex_add_metric_cards. It does not mention prerequisites (e.g., existing app), typical scenarios, or situations where another tool would be more appropriate.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe read operation. The description adds no additional behavioral context beyond that, such as the scope of 'setup requirements' or output format details.
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 a single concise sentence with no wasted words. It lacks supplementary structure but is appropriately sized for a zero-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters, an output schema present, and annotations covering safety, the description is sufficient to convey the tool's purpose. The main gap is the vague mention of 'setup requirements,' but overall context is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so there is nothing to document. A baseline of 4 is appropriate since no parameter information is needed or provided.
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 shows setup requirements and instructions for the APEX MCP server, using a specific verb ('Show') and resource. However, it does not explicitly distinguish itself from similar sibling tools like apex_check_requirements or apex_connect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description only states what it does, not when to use it or when to use another tool instead.
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?
The description only restates the core action and adds no behavioral details beyond the annotations. No mention of side effects, permissions, idempotency, or whether it overwrites existing schemes, which is significant 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 a single, front-loaded sentence that directly states the purpose without unnecessary words. It is appropriately sized for the tool's simplicity and earns its place by conveying the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a fully detailed schema and an output schema, but the description lacks usage context and behavioral disclosure (e.g., whether it replaces existing schemes or requires admin rights). These gaps make it minimally viable for an agent to invoke correctly, though not richly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the schema already explains all parameters in detail. The description adds minimal value beyond the schema, merely hinting at naming conventions in examples, which meets the baseline for schema-driven semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Create') on a specific resource ('authorization scheme'), with concrete examples (IS_ADMIN, IS_MANAGER) that distinguish it from sibling list/view tools like apex_list_auth_schemes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs. alternatives, nor when it should be avoided. There is no mention of prerequisites or comparison to other mutation tools, leaving the agent to infer usage solely from the schema.
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?
Annotations are all false, so the description carries the full burden of behavioral disclosure. It only mentions the SQL column mapping and does not disclose page-modifying effects, prerequisites, or what happens to existing regions. No contradiction with annotations exists, but the update-like nature is under-explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short clauses that fit on one line, front-loaded with the main action. Every word earns its place, and there is no 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?
The rich input schema and presence of an output schema compensate somewhat for the minimal description. However, the description lacks contextual guidance about when to choose a bubble chart over alternatives, prerequisites, or relational constraints, so an agent must rely entirely on the tool name and 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 baseline is 3. The description's 'SQL: X_VALUE, Y_VALUE, BUBBLE_SIZE, optional LABEL' adds a concise conceptual mapping to x_column, y_column, z_column, and label_column parameters, but the schema already provides detailed parameter descriptions, so the added value is marginal.
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 'Add a bubble chart' with a specific verb and resource, making the core purpose obvious. However, it does not explicitly differentiate from sibling chart tools like apex_add_scatter_plot, relying primarily on the tool name for distinction.
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?
Usage is implied by the name and one-line description, but there is no explicit guidance on when to use this tool versus alternatives. Given many chart-related siblings, no selection criteria are provided, leaving the agent to infer that a bubble chart is simply a chart type.
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?
Annotations indicate this is a mutation (readOnlyHint=false) but the description adds no further behavioral context. It does not disclose whether multiple hero banners are allowed, whether it overwrites existing banners, or any permission/side-effect details, which is a notable gap for a write 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 one concise sentence that efficiently conveys the core purpose with no wasted words. It is well-structured and immediately readable.
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?
With a rich schema and output schema present, the minimal description is adequate for basic invocation, but it lacks usage guidance and behavioral notes. Given the tool's 11 params and dense sibling list, additional context on limitations or prerequisites would improve 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 schema fully documents all 11 parameters (100% coverage) with descriptions and defaults, so the description is not required to add parameter details. It mentions 'title, subtitle, CTA button, gradient background' but these align with schema fields without adding extra semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Add' and the specific resource 'hero banner', listing key components (title, subtitle, CTA button, gradient background). This distinguishes it from sibling add-* tools like apex_add_region or apex_add_button.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool, prerequisites (e.g., page must exist), or alternatives. There is no mention of exclusions or comparison with sibling banner/components, leaving the agent to infer from the name.
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?
The description only states 'Create', which implies a write operation, but adds no additional behavioral disclosure beyond what the annotations already indicate. It does not mention side effects, permissions, idempotency, or reversibility. With all annotations false, the description carries the burden but fails to provide meaningful transparency beyond the action.
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 a single, front-loaded sentence that conveys the essential purpose without any fluff. It is appropriately sized for the tool's complexity and does not waste words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema and rich parameter descriptions (100% coverage), so the description does not need to explain return values or parameter syntax. However, the description is minimal and does not provide context about integration with pages/items or any prerequisites. It is adequate but leaves room for more contextual guidance, especially for a creation 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 parameters are well-documented in the schema. The description adds a high-level hint that the LOV can be 'static or SQL-based', which corresponds to the lov_type parameter and gives context for parameter selection. However, it does not explain parameter semantics beyond what the schema already covers, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action 'Create' and the resource 'List of Values (LOV)', with 'static or SQL-based' and 'for select items' adding specificity. This distinguishes it from sibling tools like apex_list_lovs (listing) and apex_add_item (creating items).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The phrase 'for select items' hints at context, but there is no mention of when to choose static vs SQL-based or how to reference the LOV in other tools. The schema note about referencing in apex_add_item is helpful but not part of the main description.
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?
The annotations are all false, providing no useful safety profile. The description only says 'Create', which implies a write operation but does not disclose side effects like page modification, potential overwrites, or the need for existing page objects. The schema's auto_add_js description adds such context, but the tool description itself is minimal.
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 a single, well-structured sentence that front-loads the action and outcome. No wasted words; it is appropriately concise.
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?
Although the tool has six parameters and side effects, the schema covers parameter details and an output schema exists. The description alone does not explain the workflow or prerequisites (e.g., page must exist), but the schema compensates enough to make the tool minimally usable. Basic context is present, but richer integration guidance would be helpful.
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%, and the schema itself provides detailed parameter descriptions, including a full PL/SQL example for plsql_code. The tool description adds no additional parameter semantics, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and a clear resource ('AJAX callback process (PL/SQL)') with an explicit purpose ('callable from client-side JS'). This clearly distinguishes it from sibling tools like apex_add_process or apex_generate_rest_endpoints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. While the name implies its use case, there is no explicit 'use this when...' or comparison with 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?
All annotations are false, so they offer no safety profile. The description only says 'Generate a full analytics page' without disclosing whether it creates a new page, updates an existing one, or the side effects (e.g., permissions, need for existing page_id). This is a significant behavioral gap 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 a single sentence that front-loads the core action and contains no wasted words. It is extremely brief for a complex tool, but given the schema's rich parameter details, it serves as an efficient high-level summary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a composite generator with 5 parameters and nested chart configurations, the description is too minimal. It does not clarify whether page_id refers to an existing page or triggers creation, nor the effect of page_name. The rich schema doesn't compensate for the lack of lifecycle semantics in the description.
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 already provides 100% coverage with detailed descriptions and examples for charts and metrics. The description adds a high-level mapping of page components to parameters but does not go beyond what the schema offers, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Generate' and resource 'analytics page', enumerating components 'metric cards + multiple JET charts', which clearly distinguishes it from individual adders like apex_add_jet_chart and other page generators like apex_generate_dashboard.
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 phrase 'in one call' implies this is a bulk operation that creates the whole page at once, providing some usage context. However, it does not explicitly state when to prefer this over adding components individually or using alternative generators, nor does it mention any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only states 'Add', which aligns with readOnlyHint=false, but does not disclose any additional behavioral traits such as side effects, required permissions, or where the panel is inserted. With annotations covering the basic read/write nature, the description adds no extra behavioral context beyond what is already known.
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 a single sentence that is direct and front-loaded, efficiently conveying the tool's purpose without any filler. Every word contributes to understanding the tool's 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?
Given that the schema thoroughly documents all parameters and an output schema exists, the description is sufficient to understand what the tool does. The absence of usage guidelines slightly reduces completeness, but the tool's simple add operation and rich schema compensate, making it adequately complete for invoking correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides complete descriptions for all 10 parameters (100% coverage), including format examples for metrics. The description adds no parameter-specific information beyond the general 'two columns of metrics' phrase, which is already reflected in the schema. This matches 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 adds a side-by-side comparison panel with two columns of metrics, which is a specific verb and resource. It distinguishes from sibling tools like apex_add_metric_cards or apex_add_ribbon_stats by explicitly describing the two-column layout, making its 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as apex_add_metric_cards or other visualization tools. There are no prerequisites, exclusions, or alternative tool mentions, leaving the agent without context for selection.
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?
The annotations are all false, leaving the description to explain side effects. The description only states a SQL requirement and the tool's purpose; it does not disclose that this creates a region on a page, whether it is idempotent, or what happens on conflict. This is minimal beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no superfluous content. It front-loads the purpose and includes a critical constraint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is brief and relies heavily on the schema, which is rich. However, the statement 'SQL must return a VALUE column' is misleading because the actual column name is configurable via the value_column parameter. It also omits any mention of side effects, though the output schema covers return values. Overall, it is insufficiently complete for a 10-parameter 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 coverage is 100% with detailed descriptions for all 10 parameters. The description's mention of 'min/max/thresholds' and 'VALUE column' adds no new information beyond the schema, so it meets the baseline.
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 function: 'Add a gauge/dial chart with min/max/thresholds.' It uses a specific verb and resource, and the mention of min/max/thresholds distinguishes it from sibling chart tools like apex_add_jet_chart or apex_add_sparkline.
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?
There is no explicit guidance on when to use this tool versus alternatives, but the description implies it is for gauge charts and provides a prerequisite: 'SQL must return a VALUE column.' This is helpful but does not address alternative selection.
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?
Annotations provide no safety hints (all false), and the description does not disclose behavioral traits like whether JS is appended or replaces existing code, permission needs, or lifecycle effects. 'Via Page 0' gives implementation context but not side-effect 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?
Single concise sentence, front-loaded with action and scope. Every word contributes meaning with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool affecting all pages, the description lacks behavior details (append/replace, permissions, cleanup) and does not mention output or side effects despite having an output schema. The one-liner is insufficient for an agent to anticipate consequences.
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?
Input schema covers all three parameters with descriptions (100% coverage), so baseline 3 applies. The description adds no extra semantic detail beyond naming the global scope.
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?
Clear verb 'Add' and specific resource 'global JavaScript' with scope 'all pages via Page 0'. Differentiates from sibling apex_add_page_js (page-specific) and apex_add_global_css (CSS).
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?
Implied usage for global JS across all pages vs page-specific alternatives, but no explicit when/when-not or alternative references. Missing exclusions for edge cases like needing page-specific JS or when Page 0 might not suffice.
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?
Annotations declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, meaning the tool mutates state. The description merely says 'Add' and does not disclose side effects (e.g., whether it overwrites an existing region, whether it requires unique region_name, or any permission requirements). It adds no behavioral context beyond what annotations already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with the verb first, followed by the resource and key options. Every word contributes to understanding. Extremely 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?
For a tool with 8 parameters, the schematic coverage is rich, and an output schema exists. The description adequately conveys the core purpose without needing to explain parameters or return values. It is slightly thin on rationale versus siblings, but the schema fills the 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 coverage is 100% with detailed descriptions for all 8 parameters. The description's mention of 'info/success/warning/error' and 'optional dismiss' merely echoes the schema's notification_type and dismissible descriptions. It adds no extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add') and the specific resource ('inline notification/alert'), and enumerates the supported types (info/success/warning/error) and the optional dismiss feature. It differentiates this tool from generic region-adders like 'apex_add_region', though it doesn't explicitly distinguish it from the similarly-named 'apex_add_alert_box' sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: when you want to add an inline notification/alert to a page. However, there is no explicit guidance on when to use this tool versus alternatives like 'apex_add_alert_box' or 'apex_add_region', nor any exclusions or prerequisites.
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?
Annotations are neutral (readOnly=false, destructive=false) and provide no behavioral safety profile. The description adds no context about atomicity, partial failures, reversibility, or whether existing items are affected. For a bulk mutation, this is a significant transparency gap.
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 short and front-loaded with the core action. The field list is somewhat redundant with the schema and incomplete, but it is not verbose or padded. It earns a high score for efficiency, though not top marks because the list adds little value.
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?
With a detailed input schema and an output schema present, the description does not need to explain return values. However, for a mutation tool it lacks guidance on when to use it (vs single add), behavior on repeated calls, or error handling. The description is adequate but has clear gaps in 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 coverage is 100%, so the input schema fully documents parameters. The description's field list ('name, type, label, lov, required, default') is a subset of the schema and omits optional fields like 'placeholder' and 'colspan'. It adds no new meaning beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Add'), identifies the resource ('form items'), and distinguishes from the sibling apex_add_item by highlighting 'multiple' and 'in one call'. This is a clear, non-tautological purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the name and description: use this for adding multiple items, unlike apex_add_item for single items. However, there is no explicit statement of when not to use it or a named alternative, so guidance is only implicit.
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?
Annotations already declare destructiveHint=true, and the description merely repeats the delete action without adding extra behavioral context (e.g., permanence, cascading effects, permissions required). It does not contradict annotations, but adds no value beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and target without redundancy. It is efficient and avoids 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?
The tool is a simple delete operation with fully documented parameters, an output schema, and annotations indicating destructive behavior. The one-line description is sufficient given the structured metadata; no critical information is missing. Minor gap: it doesn't state whether the button must exist or if deletion is idempotent, but annotations imply non-idempotency.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter clearly described (app_id, page_id, button_name). The description doesn't add any parameter-specific information, but the baseline of 3 is appropriate since the schema already carries the full semantic burden.
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 'Delete a button from an existing app.' uses a specific verb (delete) and resource (button), clearly distinguishing this from sibling tools like apex_delete_region or apex_delete_item. The phrase 'from an existing app' establishes the operational context cleanly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. It simply states the action without explaining when a user should choose this over other delete tools (e.g., when a button exists) or mention that the button must already be present.
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?
Annotations provide no safety hints (all false), so the description carries the full burden of behavioral disclosure. It only says 'add' without explaining side effects, such as whether it creates a new region, whether changes are reversible, or how it interacts with the page's existing layout. The description adds minimal behavioral context beyond the name.
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 a single sentence that is front-loaded with the action and resource, and includes the key differentiator (alert types). There is no wasted text; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters and an output schema, the description is minimal but the schema fills in parameter details. However, it lacks broader context such as typical use cases, how the alert box appears on the page, or how it relates to page design workflow. This is adequate but leaves gaps for an agent needing high-level 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%, so the baseline is 3. The description briefly mentions title, message, and types, but does not add meaning beyond the schema's parameter descriptions. No extra syntactical or semantic detail is provided, so it stays at the baseline.
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 action ('Add') and the resource ('styled alert box'), and specifies the supported types (info/success/warning/error) and that it includes title and message. This distinguishes it from sibling tools like add_notification_region or add_hero_banner by naming the exact component type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need an alert box) but does not explicitly state when to use it over other components like notifications or banners. No alternatives or exclusions are mentioned, so it meets only the 'implied usage' level.
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?
Annotations are all false, so the description carries the burden of behavioral disclosure. It only says 'Add' without mentioning side effects like creating/updating a region, whether existing breadcrumbs are replaced, or if any page prerequisites exist. This is a significant gap 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 a single, front-loaded sentence that immediately conveys the core purpose. It contains zero unnecessary words and is easy to parse.
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?
While the schema is thorough and an output schema exists, the description lacks essential behavioral context for a write operation, such as what side effects occur or whether it requires an existing page. It is adequate for a simple tool but does not fully compensate for the annotation 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?
The input schema has 100% parameter coverage, providing detailed descriptions for entries, page_id, sequence, and region_name. The description's mention of the entry format is redundant with the schema and adds no extra semantic value, so the baseline 3 is appropriate.
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 action ('Add') and resource ('breadcrumb navigation') and even specifies the entry format. It distinguishes from siblings like apex_add_nav_item by explicitly targeting breadcrumbs, and no other sibling handles this exact resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you want to add breadcrumb navigation) but provides no explicit guidance on when not to use it or what alternatives exist. There are no sibling tools specifically for breadcrumbs, so the usage context is inferred from the purpose.
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?
The description only repeats the action 'Add' without disclosing side effects, idempotency, failure modes, or whether the change is immediately persisted. Annotations are all false (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), offering little safety context, so the description carries the burden but does not add behavioral detail beyond the verb.
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 a single, front-loaded sentence that immediately states the action and target. Every word earns its place, and the parenthetical adds useful context 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 rich input schema and presence of an output schema, the description does not need to explain return values or parameter details. However, it lacks behavioral context (e.g., persistence, error handling, prerequisites) and usage exclusions, leaving the description functional but not fully complete for an agent operating in a complex APEX environment.
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 12 parameters. The description's parenthetical list (CREATE, SAVE, DELETE, CANCEL) partially overlaps with the button_name examples in the schema, adding no new semantics. Thus a baseline score of 3 is appropriate since 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 uses a specific verb ('Add') and resource ('button to a region'), clearly distinguishing it from sibling tools like apex_add_item or apex_add_region. The parenthetical list (CREATE, SAVE, DELETE, CANCEL, or custom) further clarifies the domain and is unique to buttons.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a button is needed in a region, but it does not explicitly state when to use this tool over alternatives or provide exclusion criteria. There is no mention of related tools like apex_add_dynamic_action for dynamic-action-based buttons or apex_delete_button for removal, though the context makes the basic intent clear.
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 provide protective hints (all false), and the description does not disclose side effects, prerequisites, or whether it modifies the page. Since the verb 'Add' is mutation, but the description doesn't elaborate on what occurs (e.g., new region created), behavioral transparency is lacking.
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 a single sentence that front-loads the core function and includes a useful SQL hint. It is extremely concise with zero wasted words.
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?
While the schema and output schema handle parameter documentation, the description lacks behavioral and contextual detail for a tool with 16 parameters. It doesn't explain how the gradient donut chart integrates with the page or what the expected outcome is beyond adding it.
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 covers 100% of parameters with descriptions, so the baseline is 3. The description adds 'SQL: LABEL, VALUE' which reinforces the sql_query parameter but doesn't provide additional semantics beyond the schema. Thus a 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Add a gradient donut chart with center label' which clearly identifies the verb (Add) and resource (gradient donut chart with center label). It also specifies the SQL column expectation (LABEL, VALUE), distinguishing it from generic chart tools like apex_add_jet_chart.
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 gives minimal usage guidance: it implies this tool is for adding donut charts, but doesn't explicitly say when to use it over siblings like apex_add_funnel or apex_add_sparkline. No exclusions or alternative recommendations are provided, so usage context is only inferred.
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?
Annotations are all false (readOnly=false, idempotent=false, etc.), so the description carries the full burden for behavioral disclosure. It only states 'Add' without mentioning side effects, idempotency, permissions, or what happens to existing regions or data. This is a mutation tool with no additional 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?
A single sentence that is front-loaded with the action and object, with zero redundant information. It is concise yet informative enough for a basic understanding.
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 (9 parameters, 3 required) and the existence of a rich schema with an example SQL, the description is adequate but incomplete. It doesn't mention prerequisites, whether it creates a new region, or how existing settings are affected. The schema fills many gaps, but the description itself omits important 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 89%, so parameters like sql_query, col_column, and value_column are already well-documented in the schema. The description adds minimal semantic context beyond the schema, only hinting that color intensity corresponds to values, which aligns with the existing parameter 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 action ('Add'), the specific resource ('heatmap grid'), and the key behavior ('color intensity based on values'). This distinguishes it from sibling tools like apex_add_jet_chart or apex_add_gauge, which add other visualization types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a heatmap grid is desired, but it provides no explicit guidance on when to use this over alternatives or any exclusions. No sibling tools are mentioned, and no conditions or prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate this is a non-read-only, non-idempotent, non-destructive operation. The description adds no further behavioral context (e.g., whether it inserts or updates a region, permissions needed, or interactions with existing page elements). It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point. No filler words or redundant information; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is fairly complex with six parameters, but the description is only one line. The output schema helps clarify return values, yet the description omits any prerequisites, side effects, or usage context, leaving the agent to infer from the schema and sibling tool names.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides high coverage (83%) with detailed descriptions for most parameters. The description adds little parameter-level meaning beyond the schema, so it does not compensate for the small gap (e.g., custom_css details are only in 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 action 'Add' and the resource: a horizontal ribbon of stat cards. It distinguishes from sibling tools by specifying the layout ('horizontal ribbon') and element type ('stat cards with icons and colors').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool compared to the many sibling tools for adding stat cards, KPI rows, or metric cards. No exclusions or alternative recommendations are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-readOnly, non-idempotent, non-destructive, and the description's 'Add' aligns with these. However, the description adds minimal behavioral context beyond the annotations, such as what exactly is created or what side effects may occur (e.g., adding a region). No contradiction exists, but it doesn't enrich the behavioral profile significantly.
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 exceptionally concise: two sentences, no fluff, with the main purpose front-loaded. The second sentence delivers a useful implementation hint without redundancy. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, a nested metrics structure, and numerous sibling visualization tools, the description is sparse. It does not explain prerequisites (e.g., existing page/region), limitations (e.g., max 7 rows for trend_sql is only in schema), or how to choose this over alternatives. An output schema exists, so return values are covered, but overall the description leaves agent guidance incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents all parameters including the detailed metrics structure. The description's 'sql + trend_sql' reiterates a subset of the schema info but adds little new meaning. It does hint at the required fields for metrics, but that is already explicit in the schema, so the description provides marginal added value.
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 adds sparkline mini-charts with trend lines, specifying both the action (add) and the resource (sparkline mini-charts). While it doesn't explicitly distinguish itself from sibling tools like apex_add_mini_charts_row, the specific mention of 'trend lines' differentiates it somewhat. It is more specific than the mere name would be.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through 'sparkline mini-charts' and 'trend lines', suggesting it is for small inline trends, but provides no explicit when-to-use or alternative guidance. The second sentence 'Provide metrics list with sql + trend_sql' reads more as parameter instruction than usage context. There are no exclusions or mentions of alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, so the agent already knows this is a write operation. The description adds that it creates a stat card with delta and trend arrow, which is consistent and adds some behavioral context. However, it does not disclose potential side effects, permissions, or whether it modifies existing regions, leaving 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 a single, front-loaded sentence that conveys the core purpose without any wasted words. It is concise and easily parsable.
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 (7 parameters, nested metrics array, SQL queries), the description is minimal. While the schema covers parameter details and an output schema exists, the description lacks usage differentiation and behavioral nuance. It explains what the card shows but not the mechanism for trend arrow or prerequisites, leaving it adequate but not 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%, and the schema already explains each parameter, including prev_sql for delta. The description adds only a high-level mention of 'current value, delta, and trend arrow', which is partially redundant with the schema. It does not provide additional parameter-level meaning beyond that.
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 'Add' and the resource 'stat card', with specific detail about its contents: current value, delta, and trend arrow. This distinguishes it from sibling tools like apex_add_metric_cards, which likely offers a more generic stat card without the delta/trend emphasis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as apex_add_metric_cards, apex_add_kpi_row, or apex_add_spotlight_metric. The description simply states what it does without any context for selection or exclusion.
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?
Annotations provide all-false hints, leaving the description to disclose behavioral traits. The description states it adds an indicator based on SQL, but does not mention side effects (e.g., page modification, requirement for existing region, behavior on duplicate names). This is a significant gap for a mutation tool with no annotation safety 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 a single, front-loaded sentence that states the essential action and purpose without wasted words. It is easily scannable and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 7 parameters, an output schema, and a simple purpose. The description is minimal but sufficient to understand the intent. However, it lacks usage context (e.g., no guidance on when to choose traffic light vs other indicators) and does not elaborate on the SQL-to-color mapping behavior despite the schema example. It is adequate but not 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?
Schema description coverage is high (86%), so the schema carries most parameter documentation. The description adds only the concept of SQL-based coloring, which is already echoed in the sql_query schema example. No additional parameter semantics beyond the schema are provided, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Add') and clearly identifies the resource ('traffic light indicator') plus the key basis ('based on SQL value'). This distinguishes it from sibling tools like gauge or metric cards, which are different visual indicators.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a SQL query should drive a red/yellow/green status display, but it does not explicitly state when to use this tool over alternatives or mention any prerequisites. No exclusions or alternative references are given, so guidance is only implied.
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?
The annotation already declares destructiveHint=true, so the destructive nature is known. The description adds minimal context by specifying 'existing app', but does not disclose side effects, irreversibility, or interact with other tools like apex_undo_last. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action. Every word is meaningful and there is no 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 simple destructive operation, the description and schema are sufficient to identify parameters and action. However, it lacks guidance on edge cases (e.g., item not found) or consequences beyond the deletion, making it merely 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?
The input schema provides 100% coverage with descriptions for app_id, page_id, and item_name, including an example and case-sensitivity note. The description itself adds no parameter-level detail, matching 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 uses a specific verb 'Delete' and resource 'item' with scope 'existing app', effectively distinguishing it from sibling tools like apex_delete_page or apex_delete_region. It clearly states the tool's purpose without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no information about when to use this tool over alternatives, nor any preconditions or exclusions. It lacks context such as needing to verify the item exists or whether deleting the item affects dependent components.
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?
Annotations are all false, offering no positive safety information. The description does not disclose whether an existing page 101 is overwritten, what other changes occur (e.g., auth scheme setup), or the non-idempotent nature implied by idempotentHint=false. This lack of side-effect disclosure is a notable 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 a single, concise sentence that front-loads the primary action and outcome, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is brief and does not mention prerequisites like app existence or behavior if page 101 already exists. While the output schema and parameter descriptions fill in some gaps, the tool's side effects and setup context are not fully captured.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all parameters well described, including a detailed auth_process_plsql example. The description itself adds no parameter semantics beyond the schema, so the baseline of 3 applies.
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 generates a login page with APEX authentication, using a specific verb ('Generate') and resource ('login page') plus a page ID. This distinguishes it from siblings like apex_add_page or apex_generate_dashboard.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating a login page, but it does not explicitly state when to use this tool versus alternatives such as apex_add_page or apex_add_auth_scheme. The schema's page_id note about matching create_app provides a hint, but no explicit usage guidance is given.
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?
Annotations are all false, providing no safety or side-effect hints. The description 'Generate' implies a creation operation but does not disclose what happens if the page ID already exists, whether authorization is required, or any other side effects. For a mutation tool, this lacks important 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the primary action ('Generate an IR report page') and a secondary qualifier (optional filter items). No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 8 parameters and an output schema, but the description is very brief. It does not explain what 'IR' stands for or mention typical prerequisites (e.g., existing app connection) or behavior on existing pages. However, the rich schema descriptions partially compensate, so it is minimally complete but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description mentions 'optional filter items' but the schema already explains filter_items in detail with examples. The description adds no new parameter meaning beyond what the schema provides, so it does not go above the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: 'Generate an IR report page' with optional filter items (text/select/date). It clearly identifies the resource (Interactive Report page) and distinguishes from sibling generators like dashboard or analytics page. The mention of filter item types adds useful specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: if you need an IR report page with optional filters, use this tool. However, it does not explicitly contrast with alternatives (e.g., apex_add_interactive_grid, apex_generate_analytics_page) or state when not to use it. There is no exclusion or alternative naming, so the guidance is only implicit.
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 all annotations false (non-readOnly, non-destructive), the description must disclose side effects and prerequisites. It only says 'generate' without explaining whether it creates a new module, overwrites existing endpoints, requires table existence, or has permission implications. The schema parameter for require_auth mentions docs only, but the description itself adds no 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the core purpose and lists the HTTP methods. It contains no filler, fluff, or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a full schema and an output schema, which covers parameter and return information. However, the description omits critical contextual details such as prerequisites (table must exist), side effects (what is created or modified), and how this fits into the broader APEX/ORDS workflow. It is minimally adequate but not 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 fully documents all five parameters. The description does not add any additional parameter semantics beyond what the schema already provides, so a baseline score of 3 is appropriate.
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 action (generate), the resource (ORDS REST endpoints), and the scope (for a table), listing the HTTP methods. This distinguishes it from sibling tools like apex_generate_crud or apex_generate_ajax_handler.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (when you need REST endpoints for a table) but does not explicitly state when to use this tool instead of alternatives, nor any prerequisites or exclusions. It is not misleading, but it lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds little behavioral context beyond 'of an existing app,' which is trivial. It does not contradict annotations, but it also does not disclose any non-obvious behaviors beyond what annotations already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence of eight words. It is front-loaded with the main verb and resource, and every word earns its place. There is no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing operation, the description is complete given the rich annotations (readOnly, idempotent, non-destructive) and the presence of an output schema. The two parameters are fully documented in the schema, and no additional prerequisites or edge cases are needed for this straightforward 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 baseline is 3 per the rubric. The description does not add additional meaning to the parameters beyond what the schema already provides; it simply reiterates the purpose. No parameter-level enrichment is offered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('page processes') for an existing app, making it clear what the tool does. However, it does not explicitly differentiate from sibling tools like apex_list_dynamic_actions or apex_list_lovs, so it misses the top score for sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description only states what it does, not in which contexts it is preferred or when other list tools should be used instead. This leaves the agent to infer usage from the name alone.
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?
Annotations are all false (readOnlyHint=false, destructiveHint=false, idempotentHint=false), providing no implicit safety profile. The description only states that it updates properties, but does not disclose behavior such as whether omitted fields are left unchanged, whether updates are reversible, or whether any fields will be overwritten. For a mutation tool, this is a significant transparency 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 a single, front-loaded sentence with no filler. It gets straight to the point and is easily skimmable. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 params, output schema present) and the schema's high coverage, the description provides a sufficient high-level purpose. However, it lacks operational context: no mention of the need for at least one new_* field to be set, no note about update semantics on existing values, and no indication of what the output contains (though output schema may cover this). It is minimally viable but not 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?
Schema description coverage is 100%, so the input schema already documents all six parameters. The description adds minimal value by naming a few properties (title, mode, auth) but omits 'new_name'. It does not clarify the null semantics (e.g., default null meaning 'no update' vs 'set to null'), though the schema hints at this. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and resource ('page properties') within an existing app, clearly distinguishing it from sibling tools like apex_update_region or apex_update_item. It also enumerates the key properties (title, mode, auth), which aligns with the input schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: use when updating page-level properties in an existing app. However, it provides no explicit guidance on when not to use it, prerequisites (e.g., app/page must exist), or alternatives like apex_add_page for creating pages. The context is clear but lacks exclusions or 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?
Annotations provide no safety hints (all false), so the description carries full behavioral burden. It mentions the item is a global variable, but does not disclose side effects, permissions required, or behavior on conflicts. The 'create' action is expected, but operational details are absent.
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 a single, clear sentence that aptly summarizes the tool's purpose without redundancy. It is front-loaded and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the schema fully describes parameters and output schema exists, the description is sufficiently complete for the core action. It clearly defines the item's scope, though it could enhance completeness by explicitly contrasting with related tools like apex_add_item.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with detailed descriptions for all three parameters, including naming conventions and protection levels. The tool description adds no additional parameter semantics, so the baseline score of 3 applies per the rubric.
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 creates an application-level item, specifying the resource (application-level item) and its distinguishing trait (global variable available on all pages). This differentiates it from sibling tools like apex_add_item, which likely targets page-level items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for global variables by stating 'available on all pages,' but it does not explicitly contrast with alternatives (e.g., apex_add_item) or provide when-not-to-use guidance. There is no explicit exclusion or alternative naming, so guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false, so no safety hints are provided. The description adds the 'toggle' behavior, which is useful context, but it does not disclose other traits such as non-idempotency (covered by idempotentHint false) or potential side effects. Minimal extra value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The single-sentence description is concise and front-loaded with the action. It earns its place, but given the tool has 7 parameters, a bit more detail could be useful without sacrificing 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?
The description, combined with the detailed input schema and output schema, covers the basic operation. However, it lacks usage context and behavioral nuances, such as whether content_sql overrides content_html or how the toggle interacts with the region. For a simple create tool, it is acceptable but not 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 86%, meaning the input schema already documents most parameters. The description does not add any parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add a collapsible/expandable region with toggle' uses a specific verb (Add) and resource (collapsible/expandable region), and the phrase 'with toggle' clearly differentiates it from siblings like apex_add_region. It directly states what the tool does without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the usage scenario (adding a collapsible region) but provides no explicit guidance on when to choose this over alternatives like apex_add_region or apex_update_region. No exclusions or prerequisites are mentioned, leaving the agent to infer based on the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false, so the description adds some context by stating it is a client-side event handler. However, it does not disclose behaviors like whether an existing DA with the same name is overwritten, whether changes are persistent, or any prerequisites such as needing an existing page or active app session.
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 a single, front-loaded sentence that efficiently conveys the core purpose. It avoids unnecessary detail or repetition, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (13 parameters, TRUE/FALSE branches), the description is minimal. It does not mention the TRUE/FALSE branch concept, conditional execution, or prerequisites like an existing page_id or active app. The output schema exists, so return values are not needed, but the conceptual model is under-explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds little beyond what the schema already explains. The partial list of actions is potentially misleading: it uses 'submit' while the schema defines 'submit_page', and it omits other action types like 'enable', 'disable', and 'plsql'. This introduces inconsistency rather than adding value.
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 action: 'Add a dynamic action' and clarifies it as a 'client-side event handler', which directly distinguishes it from other 'apex_add_*' tools. Listing example action types reinforces the purpose without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (client-side interactivity) but does not explicitly state when not to use it or reference alternative tools (e.g., apex_add_process for server-side logic). It lacks explicit usage boundaries, but the context is reasonably clear.
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?
The description does not disclose behavioral side effects, such as whether existing filters are replaced or if any page re-render is required. Annotations indicate it is not read-only, but no additional context about destructive potential or permissions is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using a compact format to convey the essence of the tool without unnecessary words. The schema carries the detail, making this appropriately sized 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?
Within the context of the rich schema and annotations, the description is adequate for understanding the tool's primary purpose, but it lacks information about prerequisites or side effects. Since an output schema is present, return values are covered elsewhere.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with detailed descriptions, especially for the facets array. The description's mention of facet structure mirrors the schema but adds no new information beyond what is already documented.
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 adds faceted search, specifying that it filters SELECT_LISTs and IR. It distinguishes from sibling tools like apex_add_search_bar by its specific focus on facets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when adding facet-based filtering to IR pages with SELECT_LISTs, but it does not explicitly contrast with alternatives or state exclusions. There is no mention of when not to use it or prerequisite conditions.
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?
Annotations show all hints false, providing no safety profile. The description discloses only the mutating action 'Add' but does not mention side effects, irreversibility, permission requirements, or behavior when duplicates exist. For a mutation tool, this is a minimal disclosure.
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 a single, clear sentence with no extraneous content. It front-loads the purpose and is efficiently concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (create nav item), the schema fully specifies parameters, and an output schema is present. The description covers the core purpose, but omits prerequisites like requiring the target page to exist, though schema details compensate.
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 covers all 6 parameters with rich descriptions, including icon examples and defaults, so the description adds no parameter-specific value. The 100% schema coverage earns a baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Add' and identifies the resource as 'navigation menu item' with a clear purpose of linking to a page. This distinguishes it from sibling add tools like apex_add_page, apex_add_region, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for adding navigation menu items, but provides no explicit guidance on when to use it versus alternatives, no exclusions, and no prerequisites. Users must infer the usage context from the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a non-read-only, non-idempotent mutation. Description only restates 'Add' and adds no extra behavioral details like side effects, auth, or idempotency, but does not contradict 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?
One sentence, front-loaded with the action and object; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema and detailed input schema, the tool can be invoked reliably despite no usage guidance; however, it lacks when-to-use 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 covers 7/8 parameters with meaningful descriptions; the description adds no parameter-level detail beyond the schema's domain (status columns), so baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States exactly that it adds a status matrix grid and defines it as rows × columns with colored status cells, making it clearly distinct from sibling add_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No information about when to choose this over alternatives such as heatmap grid or interactive grid; no prerequisites or 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?
The description discloses the rollback_on_error default, which adds behavioral context beyond the annotations (which are all false). However, it does not mention other important traits such as whether the operation is irreversible or clears the queue.
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 a single concise sentence with a parenthetical, front-loading the primary action.
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 tool with no parameters and an output schema, the description is minimal. It provides some rollback context but does not address the tool's side effects or post-conditions, leaving gaps for a mutating operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema declares zero properties, but the description references a `rollback_on_error` parameter that is not in the schema, creating confusion. This is misleading rather than additive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Execute') and resource ('all queued batch operations'), clearly distinguishing this from siblings like apex_begin_batch and apex_dry_run_preview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the final step for queued operations but does not explicitly state when to use it versus alternatives, nor mention prerequisites like beginning a batch or previewing with apex_dry_run_preview.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is clear. The description adds no extra behavioral context such as irreversibility, cascading effects, or error conditions. It neither contradicts nor enriches the annotation-provided information.
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?
A single sentence of eight words that immediately states the action. No filler or redundancy, perfectly front-loaded and easy to parse.
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 delete operation with full schema coverage and annotations, the description is adequate. It does not explain edge cases or error handling, but the presence of an output schema and annotations reduces the need for the description to cover those aspects. Missing explicit alternatives is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described ('Application ID', 'Page ID', 'Exact name of the region to delete'). The description itself adds no additional semantic details beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete') and resource ('a region from an existing app'), clearly distinguishing it from sibling tools like apex_delete_page, apex_delete_item, and apex_delete_button. It is concise and unambiguous about the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., apex_update_region for modifying, apex_add_region for creating). The description does not mention prerequisites or context such as requiring an existing region name or page.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-destructive operation. The description adds no additional behavioral context beyond stating that it exports a script; it does not mention side effects (e.g., writing to output_path) or limitations. This meets the baseline but adds nothing extra.
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 a single, front-loaded sentence: 'Export an app as SQL install script.' It contains no filler and immediately conveys the tool's purpose. It is appropriately sized for a simple tool, though perhaps too terse for broader context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, with only two parameters and strong annotations. The schema covers parameter details, and an output schema exists, so return values need not be described. The description could benefit from distinguishing it from apex_export_page, but given the other structured fields, the description is mostly adequate. A score of 4 reflects this balance.
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 for both parameters (app_id and output_path), so the schema fully documents them. The description does not expand on parameter semantics, but given the complete schema, no additional explanation is needed. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Export' with the resource 'an app' and the output 'SQL install script.' This clearly distinguishes it from siblings like apex_export_page (which exports a single page) and other generative tools. The purpose is immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool relative to its alternatives. It does not mention apex_export_page or any other sibling, nor does it specify prerequisites or exclusions. The name implies whole-app export, but the description itself lacks explicit usage direction.
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?
The annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds the score range and issues list, which is useful for expected output, but it does not add deeper behavioral context such as dependencies or side effects. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the primary action and outcome. Every word contributes to understanding, with no redundancy or tangential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters), strong annotations covering safety, and an output schema that defines the return structure, the description is complete enough. It clearly conveys the essential purpose and expected result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline score of 4 applies. The description does not need to explain parameter semantics, and the empty input schema confirms there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Run') and the resource ('APEX health check'), and specifies the output format (score 0-100 with issues list). It does not explicitly distinguish from sibling tools like apex_validate_app or apex_check_permissions, but the health check concept is sufficiently unique.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention any specific context, prerequisites, or exclusions, leaving the agent without direction on tool selection.
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?
The annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, fully covering the safety profile. The description adds no additional behavioral context, such as filtering behavior, return format, or prerequisites, so it contributes nothing beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant words, immediately and clearly stating the tool's action and target. It is efficiently front-loaded and serves its purpose 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?
Given the complete input schema, output schema, and safety annotations, the minimal description is largely sufficient for a simple read-only listing tool. It could optionally mention the region_name filter or define 'items,' but the structure already provides the necessary 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?
All three parameters are documented with descriptions in the input schema (100% coverage), so the description does not need to add parameter semantics. The description itself mentions no parameters, which is acceptable under the baseline rule 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 uses a specific verb 'List' with a clear resource 'items on a page of an existing app,' which distinctly identifies the tool's function. It differentiates well from sibling tools like apex_list_pages and apex_list_regions, 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through its phrasing ('existing app') but provides no explicit guidance on when to choose this tool over alternatives. There are no exclusions or references to sibling tools, leaving the agent to infer context from the name alone.
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?
The tool is annotated as read-only, idempotent, and non-destructive, which the description aligns with ('List'). The description adds minimal behavioral context beyond the annotations, such as the ability to target the current session or a specified app_id, but no additional operational details like pagination or filtering.
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 a single, clear sentence that front-loads the core function. No 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 simple listing tool with a single optional parameter and an output schema, this description is sufficient. It conveys the core purpose and scope, and the output schema can define the return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, app_id, is fully described in the schema with its default behavior. The description doesn't add further semantic detail beyond what the schema provides, so it 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('List'), the resource ('pages'), and the scope ('current session or an existing app'). It distinguishes from sibling tools like apex_describe_page, which describes a specific page, though it could be more explicit about what page information is returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use cases: when you need to list pages for the current session or a given app. However, it doesn't explicitly state when not to use it or mention alternatives such as apex_describe_page for page 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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds minimal behavioral context beyond the annotations, such as the fact that it lists 'all users' (unfiltered). However, it does not disclose potential behavior like pagination, ordering, or permission requirements, so it meets the baseline but does not exceed it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no filler or redundancy. It immediately states the action and object, effectively front-loading the core purpose.
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 simplicity of the tool (one optional parameter, output schema present, rich annotations), the description is largely sufficient. It clearly indicates the tool's scope and action. However, it does not mention any prerequisites like being connected to an APEX workspace or authentication, which might be inferred from the presence of a separate apex_connect tool. This is a minor gap, so not a perfect score.
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% coverage, with workspace_id described as 'Workspace ID (defaults to configured workspace).' The tool description does not add any additional meaning to the parameter; it only repeats the workspace scope. With high schema coverage, the description does not need to compensate, so baseline 3 is appropriate.
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 function: 'List all users in the APEX workspace.' It uses a specific verb (List) and resource (users) along with a clear scope (APEX workspace), which distinguishes it from sibling tools like apex_create_user or apex_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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, exclusions, or context such as 'use this when you need to review existing users before assigning permissions.' The usage context is entirely implied by the tool's name and purpose.
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?
Annotations are all false, providing no positive safety cues, so the description carries the burden. It explains lifecycle timing but does not disclose potential side effects, required permissions, or the fact that creating a process may alter app behavior across all pages. For a creation tool, this is a significant 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 a single, front-loaded sentence that efficiently conveys the core purpose without extraneous detail.
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?
With 6 parameters, an output schema, and no meaningful annotations, the description is minimal but sufficient given the rich schema. It covers what the tool does but lacks guidance on usage scenarios and behavioral implications, making it minimally viable.
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 in detail. The description adds no extra parameter-level meaning, making the baseline 3 appropriate.
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 creates an application-level process and explicitly distinguishes it from page-level processes by noting it runs on every page load or session init. This differentiates it from sibling tools like apex_add_process.
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 parenthetical 'runs on every page load or session init' gives clear context on when to use this tool for application-wide processes. However, it does not explicitly exclude alternatives or mention when to prefer page-level processes, so it lacks explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds meaningful behavioral context by specifying the SQL alias requirement and the supported chart types, which goes beyond the structured annotations. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: three short sentences or fragments that immediately state the action, list types, and give the key SQL constraint. No filler words, front-loaded with the core purpose. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 15 parameters and many sibling chart tools, the description is minimal. It covers the core purpose and a key constraint, but does not orient the agent among the extensive sibling chart tools (e.g., combo, area, bubble). The rich output schema and parameter descriptions compensate, but the lack of tool selection guidance makes it less 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%, with every parameter having detailed descriptions (e.g., chart_type enumerates all options with explanations, sql_query includes an example). The description's note 'SQL must alias LABEL + VALUE' reinforces the sql_query parameter but adds little beyond the schema. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Add an Oracle JET chart region' with a verb and resource. It lists common chart types (bar, line, pie, donut, area), but does not explicitly differentiate from the many sibling chart tools like apex_add_area_chart or apex_add_combo_chart. The schema reveals additional types (combo, bar_horizontal) not mentioned, so purpose is clear but not fully distinguishing.
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 an important usage prerequisite: 'SQL must alias LABEL + VALUE.' However, it gives no guidance on when to use this tool versus specialized chart siblings (e.g., apex_add_pareto_chart, apex_add_scatter_plot). Usage context is implied (general JET chart addition) but no explicit alternatives or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate this is not read-only and not idempotent, but provide little else. The description adds the important behavioral trait that an import session is started and must be finalized with apex_finalize_app(). However, it does not explain the session lifecycle, side effects, or what happens if finalization is skipped.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loading the primary action and including a necessary follow-up instruction. No redundant words or filler.
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 tool with 10 parameters and a session-based workflow, the description is thin. It mentions the finalize dependency but does not explain what an 'import session' is or how this tool fits into the broader app-creation workflow. The output schema likely provides return values, but the workflow context is incomplete.
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?
All 10 parameters have thorough descriptions in the schema (100% coverage), so the description does not need to repeat parameter details. The description adds no parameter-specific guidance beyond schema, which is acceptable given the 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 action: 'Create a new APEX app and start an import session.' This distinguishes it from siblings like apex_finalize_app, apex_delete_app, and apex_export_app by marking it as the creation step. The verb 'create' and resource 'APEX app' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage guidance is 'Call apex_finalize_app() when done,' which implies a sequential workflow but does not explicitly state when to use this tool versus alternatives or any prerequisites. The context suggests this is the initial step in app creation, but exclusions and alternative selection criteria are absent.
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?
All annotations are false, so the description carries the full burden of behavioral disclosure. It states that pages and DML processes are generated, but does not mention that this modifies the current app, whether existing pages with the same IDs will be overwritten, or any side effects. This leaves significant behavioral uncertainty 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 a single, well-structured sentence with no filler words. It front-loads the core deliverable ('full CRUD') and specifies the components, making it highly concise.
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 rich schema and output schema, the description is minimally viable: it communicates the primary purpose. However, it omits important context such as app-targeting behavior, potential overwrites, and prerequisites, so it is not fully complete for a tool with 11 parameters.
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 11 parameters in detail. The description adds no parameter-specific information, thus meets the baseline of 3 but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Generate') and clearly specifies the resource ('full CRUD: IR list page + form page with DML processes for a table'). This distinguishes it from sibling tools like apex_generate_report_page or apex_generate_dashboard, which have narrower scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: when a full CRUD interface for a table is needed. The phrase 'full CRUD' and the mention of both list and form pages provide clear context, though it does not explicitly name alternatives or exclusions.
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?
All annotations are false/non-indicative, so the description must carry the burden of behavioral disclosure. It reveals the generated artifact (wizard with steps, progress bar, navigation) but does not disclose side effects, such as page creation/overwriting behavior, permissions required, or consequences of using existing page IDs. This is a significant gap for a generation 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 a single, front-loaded sentence with no filler. It packs the verb, object, scope, and key features efficiently, earning its place with every word.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The combination of full parameter schema coverage, an output schema, and the concise description covers the basic invocation needs. However, important contextual elements—side effects, prerequisites, and alternatives—are missing, leaving the agent with only partial information for safe and confident use. For a mutating generation tool, this is adequate but not complete.
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 already documents all parameters with 100% coverage, so the baseline is 3. The description adds a useful hard constraint—'2-6 steps'—which is not present in the schema, helping the agent validate input. It does not add detail for other parameters, but the schema descriptions are already sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Generate') and identifies the exact resource ('multi-step wizard') with key characteristics (2-6 steps, progress bar, items, navigation buttons). This clearly distinguishes it from sibling tools like apex_generate_dashboard or apex_add_progress_tracker, and the scope is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when a multi-step wizard is needed. However, it provides no explicit guidance on when not to use it or which alternative tools to prefer, such as simpler form generators or single-step page builders. The 2-6 step constraint offers some context but no explicit exclusions.
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?
The description discloses core behavioral traits (editable, add row), but annotations provide no safety hints (all false). It does not mention side effects like modifying the page, creating a region, or potential overwrite risks. Since annotations are silent, the description only partially carries the burden of 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with two short sentences that front-load the primary purpose and core features. Every word contributes meaning, with no filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 8-parameter complexity and a rich output schema, the description provides a sufficient overview of the tool's purpose and key features. It doesn't explain custom SQL or DML operations, but those are covered in the schema. For a tool with this many siblings, a bit more context on when to choose IG over other region types would improve completeness, though it is already 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 baseline is 3. The description's 'inline editing' and 'add row' align with the 'editable' and 'add_row' parameters, but it doesn't add new meaning beyond what the schema already provides. It lacks extra context like SQL override or DML behavior.
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 action ('Add') and the resource ('Interactive Grid'), with a clarifying parenthetical '(editable spreadsheet)' that distinguishes it from other region/chart tools. The mention of 'inline editing' and 'add row' further differentiates it from siblings like apex_add_region or apex_add_jet_chart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through key features ('Supports inline editing + add row') but does not explicitly state when to use this tool versus alternatives or when not to use it. No exclusions or alternative tool names are provided, so the guidance is indirect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutating operation (readOnlyHint=false, destructiveHint=false). The description adds the detail about the hidden PL/SQL region, which is a behavioral trait not visible in annotations. However, it doesn't disclose side effects like whether existing CSS is replaced or appended, or any ordering implications. The extra context is minimal but non-contradictory.
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 a single, compact sentence of 12 words. It is front-loaded with the key action ('Add inline CSS') and efficiently conveys the target and mechanism without any filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two well-documented parameters, an output schema exists, and annotations provide safety signals. The description covers the core purpose and mechanism adequately. It lacks explicit usage guidance, but given the simplicity and available metadata, it is fairly 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 coverage is 100% with descriptions for both page_id and css_code. The description doesn't add any extra parameter context beyond what the schema already provides, so the baseline score of 3 is appropriate.
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 action ('Add inline CSS') to a specific resource ('a specific page') and includes the mechanism ('via a hidden PL/SQL region'). It effectively distinguishes from sibling tools like apex_add_global_css and apex_add_page_js by specifying page-level CSS.
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 phrase 'to a specific page' implies this is for page-scoped CSS rather than global CSS, but it doesn't explicitly state when to use this versus alternatives like apex_add_global_css. No exclusions or alternative guidance are provided, leaving usage implications rather than explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the description is consistent with a mutating but non-destructive operation. The description adds the visual detail of 'horizontal steps with active state' but does not disclose side effects like region creation or page requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tight sentence that immediately states the action and object, with a brief parenthetical clarifying the component style. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a component-add tool with 8 parameters and a full output schema, the description is adequate: it names the action and the component type. However, it does not explain the intended use case (e.g., multi-step wizard flows) or note that steps must be provided as an array, though the schema covers this. Overall, it is minimally complete but not rich.
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?
All 8 parameters are fully described in the schema (100% coverage). The description adds no parameter-specific meaning beyond the schema's existing descriptions, such as 'List of step labels' and 'Active step number (1-based)'. 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 uses the specific verb 'Add' with a specific resource 'step progress tracker' and clarifies the visual form ('horizontal steps with active state'). This clearly distinguishes it from siblings like add_region or add_item.
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 does not explicitly state when to use this tool versus alternatives. Usage is implied by the component name and the brief parenthetical, but there are no exclusions or alternative tools mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false, offering no safety profile, so the description carries the burden. It discloses that the search bar filters via a Dynamic Action and implies a page modification, but it does not mention side effects like potential duplicate regions, dependencies on the IR region's structure, or reversibility. This provides some useful behavioral context but leaves 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 entire description is a single, front-loaded sentence with no filler. Every phrase adds meaning, and it is appropriately sized for the tool's simplicity.
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 has a rich input schema (7 params, 100% covered) and an output schema, the one-line description is mostly sufficient for selecting and invoking it. It clearly states the core functionality and the mechanism, though it omits any edge-case warnings or prerequisites. This is complete enough for typical use but not exhaustive.
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?
Input schema covers 100% of parameters with descriptions, so the baseline is 3. The tool description adds a small amount of context by explaining the overall function (filters on keystroke), which helps interpret parameters like target_region_name, but it does not detail parameter-specific behavior beyond the schema. Therefore a neutral score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Add') and resource ('search bar'), and clarifies the functional behavior (filters an IR region on keystroke via Dynamic Action), which clearly distinguishes this tool from sibling add_* tools like apex_add_region or apex_add_item. It leaves no ambiguity about what the tool accomplishes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a use case (adding a search bar for an IR region with keystroke filtering) but does not explicitly state when to choose this over alternatives, such as manually creating a text item and dynamic action, or mention prerequisites like the target region being an Interactive Report. Thus the guidance is present only by implication.
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?
The description discloses that the tool adds a region and requires the SQL to return specific column aliases, which is a key behavioral constraint. Annotations are all false and provide no additional safety information, so the description carries the burden. It does not mention side effects, permissions, or undo behavior, but for a simple additive tool this is minimal but acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, and contains zero filler. Every word earns its place, making it an excellent example of conciseness.
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 has 8 parameters with complete schema descriptions and a declared output schema, the description need not explain return values. The main gap is lack of usage guidance relative to sibling region tools, but the schema and the stated SQL requirement together provide enough information for correct invocation. Slightly below perfect due to missing alternative guidance.
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 parameters. The description's SQL column requirement adds marginal value by connecting sql_query to date_col, title_col, and body_col, but this is largely redundant with the schema descriptions. No additional parameter meaning is provided 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 uses a specific verb and resource: 'Add a vertical timeline region.' This clearly distinguishes it from sibling tools like apex_add_calendar or apex_add_activity_stream. The required SQL columns are also stated, further clarifying the tool's specific purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a timeline region is needed, and the SQL requirement provides a prerequisite. However, it does not explicitly mention when to use this over generic region tools (e.g., apex_add_region) or provide exclusion criteria. No alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which convey safety and non-mutating behavior. The description adds no additional behavioral context beyond stating the action (check), so it does not meaningfully supplement the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that directly states the tool's action and scope. No filler or redundancy; it earns its place entirely.
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 simplicity (no params, read-only annotations, and an output schema), the description adequately states what it checks. However, it lacks explicit relationship to sibling tools like apex_check_requirements or apex_fix_permissions, which could help the agent choose correctly in ambiguous contexts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description does not need to explain parameters since the schema is empty and the purpose is clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Check' with a clear resource: 'Oracle grants and APEX object access permissions.' It clearly differentiates from siblings like apex_check_requirements (checks requirements) and apex_fix_permissions (fixes permissions).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as apex_check_requirements or apex_fix_permissions. It does not state any prerequisites, exclusions, or typical scenarios, leaving the agent to infer usage solely from the name.
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?
While annotations already indicate destructiveHint=true, the description adds the critical context that the deletion is 'permanently' — meaning irreversible. This goes beyond the annotation by clarifying the permanence and lack of recovery, which is essential for a delete 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 a single, front-loaded sentence with no wasted words. It efficiently conveys the action and its key qualifier ('permanently') without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple one-parameter schema, the presence of an output schema, and annotations covering destructiveness, the description is largely complete. It could be argued that more detail about side effects (e.g., deleting all associated components) is needed, but the word 'permanently' and the existing structured data suffice for a basic 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?
The input schema already provides a clear description for the single parameter (app_id), achieving 100% coverage. The tool description does not add additional meaning beyond the schema, so the baseline score of 3 is appropriate.
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 a specific action (delete) and resource (APEX application), with the qualifier 'permanently' reinforcing the scope. It distinguishes from sibling delete tools (e.g., apex_delete_page, apex_delete_region) by explicitly targeting the application level.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as exporting the app first or using preview/undo tools. The description implies it's for removing an app, but there are no explicit exclusions or alternative recommendations, which is especially important for a destructive operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive and non-read-only behavior. The description confirms the destructive nature but adds no further behavioral context (e.g., irreversibility, cascade effects, or permission requirements). It does not contradict 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 a single, efficient sentence that immediately states the operation, front-loading the core purpose. It contains no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a simple two-parameter operation, an output schema, and annotations covering destructive behavior, the description is sufficient for the agent to understand the tool's primary effect. It does not elaborate on potential side effects, but that detail is not critical given the structured 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 coverage is 100%, so parameters app_id and page_id are fully described in the schema. The description does not add additional parameter meaning beyond what the schema already provides, making a baseline score of 3 appropriate.
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 action (delete) and the resource (a page). It distinguishes from sibling tools like apex_delete_app or apex_delete_region by being specific to 'page' deletion, aligning with the tool name apex_delete_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for deleting a page but provides no explicit when-to-use, when-not-to-use, or alternative tool references. The constraint about page 0 is in the schema, not the description, so within the description itself, guidance is limited to the implied 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?
Annotations already declare this as a read-only, idempotent, non-destructive operation. The description adds that output is in human-readable text, which gives some context on output format, but no further behavioral details such as pagination or depth of component listing. It does not contradict 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 a single, concise sentence with no redundant words. It is front-loaded with the action and resource.
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 simplicity, the description, schema, and annotations cover essential aspects. The output schema exists, so return values are specified elsewhere. However, 'components' is somewhat ambiguous and could be clarified to indicate whether it includes regions, items, processes, etc., which would help distinguish from more specific list tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both app_id and page_id. The description does not add additional parameter semantics beyond what the schema already provides. Baseline of 3 is appropriate.
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 function: describing a page's components in human-readable text. The verb 'describe' and the target resource 'a page's components' are specific, and the output format is noted. This distinguishes it from sibling tools like apex_list_pages or apex_describe_table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a human-readable overview of a page's components is needed, but it does not explicitly state when to use this tool instead of alternatives like apex_get_page_details or apex_list_regions. No exclusions or alternative mentions are provided. Usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a read-only, idempotent, non-destructive operation. The description adds only the scope ('between a list of tables') and does not disclose additional behavioral details such as detection methodology, limitations, or handling of invalid input. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no redundant words; front-loads the core action and resource. Highly concise 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?
For a simple, read-only tool with one well-documented parameter and an output schema, the description is adequate. However, it could slightly clarify whether 'auto-detect' means potential relationships or existing constraints, and whether any prerequisites apply. Overall, sufficient for the task.
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 sole parameter 'tables' is fully described in the schema (100% coverage), including case-insensitivity. The tool description's 'between a list of tables' echoes the schema without adding new semantic information, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool's function: auto-detecting foreign key relationships among a provided list of tables. Uses a specific verb ('auto-detect') and resource ('FK relationships'), distinguishing it from sibling tools like apex_describe_table or apex_generate_from_schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when FK relationships need to be identified among given tables, but it provides no explicit guidance on when to prefer this tool over alternatives, nor any when-not-to-use conditions. No exclusions or alternative tool mentions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds that the diff covers pages, regions, and items, but does not elaborate on process, return behavior, or any other behavioral traits beyond this scope.
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 a single, succinct sentence that front-loads the main action ('Compare app structure') and adds a clarifying clause. Every word is purposeful with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relatively simple two-parameter diff tool with a full output schema and annotations covering side effects, the description provides enough context about the tool's purpose and scope. It could mention version semantics or time-frame assumptions, but the existing details are mostly 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%, and both parameters (app_id_1, app_id_2) have clear descriptions like 'First application ID (base)'. The tool description does not add any additional parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly specifies the verb 'Compare' and the resource 'app structure', and details the diff scope (pages, regions, items). This distinguishes it from sibling tools like apex_describe_page or apex_get_app_details, which focus on single states.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for comparing two app versions but does not explicitly state when to use this tool over alternatives or when not to use it. There are no exclusionary or conditional statements, leaving usage slightly inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the scope of documentation (pages, regions, items) but does not disclose additional behavioral traits such as return format, side effects, or any requirements. This is consistent with annotations and adds moderate context beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the main purpose and scope ('Auto-generate Markdown documentation for an app (pages, regions, items)'). Every word contributes useful information with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, output schema present, strong annotations), the description covers the core purpose and scope adequately. It does not mention when to use it or what happens with the generated docs, but the existing structured data mitigates the need for further detail. The description is slightly thin on usage context but remains sufficient for this low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description already explains that app_id defaults to session.app_id. The tool description adds no further parameter-specific semantics, so the baseline of 3 is appropriate given the 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 function: 'Auto-generate Markdown documentation for an app (pages, regions, items).' It uses a specific verb ('auto-generate'), identifies the resource ('Markdown documentation for an app'), and scopes the content to pages, regions, and items. This distinguishes it from all sibling tools, including apex_describe_page, which focuses on a single page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for generating app documentation but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. Sibling tools like apex_describe_page or apex_get_app_details might serve similar contexts, but the description does not mention them, so usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, and the description aligns by saying 'Get'. The description adds context about the scope (pages, auth, theme) but does not disclose potential edge cases like app existence validation, response size, or performance implications. It adds some value but is not rich.
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 a single, front-loaded sentence that states the purpose and key content areas without any filler. Every word contributes, making it adequately concise 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?
For a simple read-only operation with one parameter and an output schema, the description is largely complete. It identifies the app as 'existing', implies the need for a valid app_id, and mentions the major metadata categories. Minor gaps like error behavior or dependency on a connection are not addressed, but the output schema covers return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with app_id described as 'Application ID to inspect.' The description adds no additional parameter-specific meaning beyond what the schema already states. With full schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' and identifies the resource as 'full metadata for an existing APEX app', explicitly listing components (pages, auth, theme). This clearly distinguishes it from siblings like apex_get_page_details, which targets page-level metadata, and apex_list_apps, which lists apps rather than returning app metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: use when you need full app-level metadata. However, it does not explicitly compare to alternatives or state when not to use it. The distinction from page-level tools is implicit through the phrase 'full metadata for an existing APEX app', but no explicit guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds no further behavioral details (e.g., sorting, pagination, error conditions), but also does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It communicates the essential function and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two well-documented parameters and an output schema exists, so the description does not need to detail return values. 'Existing app' implies the app must exist, which is adequate. It could mention ordering or filters, but these are likely covered by the 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?
The input schema provides 100% coverage with descriptions for both app_id and page_id. The tool description adds no additional parameter semantics, but none are needed given the self-explanatory names and schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('List regions') and clearly scopes to 'a page of an existing app,' distinguishing it from sibling tools like apex_list_pages or apex_add_region.
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 does not explicitly state when to use this tool over alternatives or provide exclusions. The context is implied by the name and phrasing, but there is no guidance on when not to use it or when to prefer a sibling like apex_list_items.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the key behavioral traits (idempotent, non-destructive, non-read-only). The description adds the contextual source ('live database') but does not explain side effects such as whether local templates are overwritten or if a database connection is implicitly required. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and scope with no unnecessary 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 simple tool with no parameters and an existing output schema, the description captures the essential purpose. It does not mention when to use it or prerequisites, but the specific scope and annotations make it adequately complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is empty. The baseline for no parameters is 4; the description does not need to add parameter-level detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Refresh'), a clear resource ('Universal Theme 42 template IDs'), and a source ('the live database'). This distinguishes it from all sibling tools, as no other target template refreshing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor are prerequisites or exclusions mentioned. For a refresh operation, it would benefit from a note on when a refresh is needed or whether it must be run after certain actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive behavior. The description adds scope ('last created') but does not disclose limitations such as what happens when there are no components to undo or whether undo itself is reversible. This is adequate given the annotation coverage but not rich.
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 a single sentence, front-loaded, and contains no unnecessary information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with full schema coverage and annotations indicating destructive safety, the description is nearly complete. It does not specify behavioral limits or return values, but output schema and annotations cover those aspects.
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 fully documents the single optional 'steps' parameter with a description and default. The tool description adds no extra meaning to the parameter, so the baseline 3 applies.
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 undoes the last created component and provides examples (region, item, button). This verb+resource phrasing distinguishes it from sibling tools like delete or add operations.
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?
Usage is implied by the verb 'undo' but there is no explicit guidance on when to use this vs alternatives like delete, or what 'last' means in context. No exclusions or edge cases are mentioned.
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?
All annotations are false, so the description carries the full burden. It discloses a key behavioral requirement (SQL alias and ordering), but does not mention side effects, permissions, or what happens upon completion. The addition of the SQL constraint provides some transparency, but it is minimal 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 a single sentence with no filler. It front-loads the primary action and then gives the essential SQL requirement. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has nine parameters and moderate complexity. The description gives the critical SQL requirement but lacks context on when to use it compared to other chart tools or what the resulting page change looks like. The presence of an output schema mitigates some ambiguity about return values, but for a mutation tool with neutral annotations, a bit more context would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds the explicit alias requirement for LABEL and VALUE, which is already implied by the schema example and label_column/value_column defaults. It provides marginal added meaning 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 begins with 'Add a funnel chart,' which clearly states the specific verb and resource. It also includes a distinctive SQL requirement that differentiates it from sibling chart tools like apex_add_jet_chart or apex_add_gauge.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear usage constraint: 'SQL must alias LABEL + VALUE ordered by sequence.' This tells the agent when the tool is applicable and what prerequisites must be met. However, it does not explicitly mention alternatives or when not to use it, so it falls short of a 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?
Annotations already indicate this is not read-only (readOnlyHint false) but also not destructive (destructiveHint false). The description adds the sequencing requirement but does not disclose whether finalization is reversible, what side effects occur, or what happens if called prematurely. There is an apex_undo_last sibling, but the description doesn't address undoability. So some transparency but 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 a single sentence, front-loaded with the action, and includes only necessary contextual information ('Must be called after...'). No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description covers the essential purpose and timing. It could elaborate on the finalization process and any irreversible effects, but given the simplicity and output schema presence, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, making schema coverage 100%. The description correctly adds no parameter information since there are none. Per baseline for 0 parameters, the score is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Finalize and commit the app') and the resource. It also notes the required ordering relative to adding pages/components, helping distinguish it from other app-level operations like apex_commit_batch or apex_dry_run_preview. Slightly vague on what 'finalize' entails, but the intent is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Must be called after all pages/components are added,' providing a clear precondition and timing guideline. It implies this is the final step, which distinguishes it from preview/validate tools. Does not mention alternative tools or exclusions, but the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds minimal context about the app being existing, but does not disclose behavior like error handling or pagination. With annotations present, this is adequate but not rich.
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 a single sentence that puts the verb first, identifies the resource, and is free of extraneous words. Every word adds value, making it highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, read-only listing tool with one parameter, an output schema present, and comprehensive annotations, the description is sufficient. It clearly states what the tool does, and the structured data covers safety, parameters, and return types. No additional context is necessary for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully covers the single parameter app_id with its description 'Application ID' (100% coverage). The tool description does not add any additional semantic meaning about the parameter beyond what the schema provides, so the score remains at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and resource 'authorization schemes' with scope 'in an existing app', clearly distinguishing it from other listing tools like apex_list_apps or apex_list_pages. It is unambiguous and immediately conveys the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'in an existing app' implies that the tool is intended for apps that already exist, but the description does not explicitly state when to use this tool relative to alternatives such as apex_add_auth_scheme or apex_get_app_details. There is no mention of exclusions or alternative tools, making the usage guidance merely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds 'with row counts' and 'tables/views' as behavioral details. It does not describe limitations like views having NULL row counts (though the schema does), but given annotations, it provides adequate additional 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 a single, front-loaded sentence that states exactly what the tool does without any wasted words. It earns its place fully.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool, the description is complete: it states the purpose, the scope, and the key output feature (row counts). With annotations covering safety and an output schema present, no further explanation is needed.
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 parameters are fully documented in the schema. The description does not add any parameter-specific meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.
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 lists all tables/views in the current Oracle schema with row counts. It uses a specific verb ('List') and resource ('tables/views'), and specifies the scope ('current Oracle schema'), distinguishing it from sibling tools like apex_describe_table.
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?
Usage is implied (for getting a schema overview) but there is no explicit when-to-use guidance or mention of alternatives such as apex_describe_table for specific tables. The description provides clear context but lacks exclusions or alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds useful detail about the output format (f?p=APP:PAGE), which goes beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no fluff. It conveys the essential purpose and output format efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the rich annotations, 100% schema coverage, and presence of an output schema, the description is sufficiently complete. No additional context is necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and both parameters (app_id, page_id) have clear descriptions in the schema including defaults. The tool description adds no extra parameter information, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('the preview URL for a page'), and includes the URL pattern 'f?p=APP:PAGE' for clarity. This clearly distinguishes it from siblings like apex_describe_page or apex_dry_run_preview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as apex_dry_run_preview. The description simply states what the tool does without any context, prerequisites, or exclusions.
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 all annotations false, the description carries the burden. It discloses the implementation mechanism ('via Page 0') and global reach, but it does not clarify whether CSS is appended or replaced, or what happens if called multiple times—important given idempotentHint=false. Some behavioral context is provided, but not complete.
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 a single, concise sentence that is front-loaded and contains no filler. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one fully documented parameter and an output schema, the description covers purpose, scope, and use case adequately. Missing explicit caveats or references to alternative tools, but overall it is sufficiently 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 coverage is 100%, so the baseline is 3. The description adds a minor use-case context ('branding and theme overrides') but does not provide additional parameter-level details beyond what the schema already includes.
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 action ('Add global CSS'), the scope ('ALL pages via Page 0'), and the intended use case ('branding and theme overrides'). It effectively distinguishes itself from siblings like apex_add_page_css (page-specific CSS) and apex_add_global_js (JavaScript).
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?
It explicitly identifies when to use this tool ('Use for branding and theme overrides') and the global scope, but it does not explicitly mention alternatives or when not to use it. The context is clear but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false) and non-destructive behavior; the description adds context by specifying 'server-side' and listing validation categories. However, it mentions 'SQL' as a supported type while the input schema's validation_type options do not include an explicit 'sql' type, which could mislead an agent. It also does not disclose whether repeated calls create duplicate validations.
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 a single sentence, front-loaded with the verb and object, and contains no unnecessary filler. The parenthetical list is compact and helpful despite the minor 'SQL' ambiguity.
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 rich input schema (100% parameter coverage) and the presence of an output schema, the description does not need to explain return values or param syntax. It adequately complements the schema by stating the tool's purpose, though it could be slightly more explicit about duplicate behavior and the exact validation types supported.
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 detailed explanations and examples for all 8 parameters, including validation_type options and expression formats. The description itself adds little parameter-specific meaning beyond the summary list of validation types, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Add') and a clear resource ('server-side validation to a page item'), and the parenthetical enumeration of validation types further clarifies scope. This distinguishes it from sibling tools like apex_add_process or apex_add_item_computation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: this tool adds server-side validation to a page item, which implies when it should be used. It does not explicitly name alternatives or exclusions, but the 'server-side' qualifier and resource focus provide enough situational clarity for most agents.
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?
The description discloses a key behavior—row click in master refreshes detail—which is valuable. However, it does not mention other side effects such as the creation of a hidden item or dynamic actions, and the annotations are all false, providing no safety context. The description carries the burden but only partially covers the behavioral impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short, front-loaded sentences with no filler. Every word contributes to understanding the tool's purpose and key behavior, making it an excellent example of concise communication.
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 rich schema descriptions and availability of an output schema, the description does not need to explain return values or parameter details. It provides the essential behavior (master-detail interaction) and is complete enough for an agent to understand the tool's role, though it could mention prerequisites like existing page.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already thoroughly documents all parameters, including the hidden item binding and SQL examples. The description adds no additional parameter-level meaning, so the baseline score of 3 is appropriate.
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 the resource 'master IR + detail IR on same page', which precisely defines the tool's function. It also distinguishes from sibling tools like apex_add_region or apex_generate_crud by specifically targeting an interactive report master-detail pairing.
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 context of creating master-detail IRs on the same page is clearly conveyed, and the row-click refresh behavior implies the intended use case. However, the description doesn't explicitly mention alternatives or when not to use this tool, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds the valuable behavioral detail 'Cached per session,' which is not available in annotations. This explains why repeated calls may return stale data without requiring force_refresh.
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 a single short sentence (7 words) that front-loads the core purpose and includes a useful behavioral note. No wasted words; every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only describe tool with an output schema and comprehensive annotations, the description covers purpose and caching behavior. It does not explicitly mention output structure or validation, but the output schema fills that gap. It could mention that it is read-only (though annotations already do), so it is complete enough.
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 covers 100% of parameters with descriptions, so the baseline is 3. The description's 'Cached per session' adds context for force_refresh but is already implied by the schema's 'Bypass cache'. No additional parameter semantics are provided 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 uses the specific verb 'Describe' and identifies the resource ('table') with explicit outputs ('columns, types, PKs, and FKs'). It clearly distinguishes from sibling tools like apex_list_tables (which likely lists tables) and apex_run_sql (general SQL execution).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for inspecting table schema but provides no explicit guidance on when to choose this over alternatives. The phrase 'Cached per session' hints at repeated use, but no exclusions or alternative recommendations are given. It is clear in context but lacks explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the export format but does not disclose other behavioral aspects like the 32 KB response limit, which is in the schema rather than the description. It does not contradict 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 a single sentence that conveys the core purpose without waste. It is front-loaded and easy to parse.
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 low complexity of the tool, a rich input schema with 100% parameter coverage, and the presence of an output schema, the description is adequate. It could mention the difference from apex_export_app, but the name and phrasing already imply the scope.
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 no additional parameter information beyond what is already in the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Export') and resource ('a single page') and specifies the output format ('SQL install script'). It clearly distinguishes from sibling tools like apex_export_app, which exports the whole app, and apex_describe_page, which describes a page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'single page' gives clear context for when to use this tool versus apex_export_app. However, it does not explicitly state when not to use it or mention alternatives beyond what the name implies.
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?
The description discloses the main output (app with CRUD, dashboard, navigation) but does not reveal important behavioral details such as whether it creates a new app or adds to the current one, whether it overwrites existing pages, or whether it is idempotent. Annotations are all false, offering no safety hints, so the description carries the burden but falls short of full 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 a single, concise sentence that front-loads the core purpose and key deliverables. Every word earns its place, with no fluff or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex generation tool with an output schema present, the description provides a clear high-level picture and the schema covers parameter details. It is missing some contextual information about side effects and prerequisites (e.g., whether it requires an existing app), which prevents a perfect score, but it is sufficiently complete for an agent to understand the tool's main function.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with well-documented parameters including examples and defaults. The description does not add any parameter-specific meaning beyond the schema, so it does not go beyond the baseline. However, the schema is thorough, so the description does not need to compensate.
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: 'Generate a complete app from a list of tables: CRUD pages + dashboard + navigation.' It uses a specific verb ('Generate'), identifies the resource ('complete app'), and specifies the key components (CRUD pages, dashboard, navigation). This distinguishes it from sibling tools like apex_generate_crud (which likely handles a single table) and apex_create_app (which may create an empty app).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear context for when to use the tool: when you have a list of tables and want a complete app with CRUD, dashboard, and navigation. It does not explicitly mention alternatives or when not to use it, but the context is strong enough for an agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds that it shows specific information (connection, session, app), but nothing beyond that—no notes on behavior when disconnected, error handling, or what 'active app' means. It doesn't contradict 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 a single, front-loaded sentence that conveys the core purpose without any wasted words. It is appropriately sized for a tool with no parameters and a clear 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?
Given no parameters, strong annotations, and the presence of an output schema, the description is largely complete. It tells the agent what the tool does and what it reports. It doesn't elaborate on usage scenarios or edge cases, but those are not essential for a simple status check tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds no parameter-specific information, but none is needed. The output schema likely describes the returned structure, so this is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does with a specific verb 'Show' and names the exact resources it reports on: connection status, session state, and active app. This distinguishes it from sibling tools like apex_connect (which establishes a connection) and apex_health_check (which likely checks overall health).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when you need to see connection/session/app status) but provides no explicit guidance on alternatives or when not to use it. There's no mention of prerequisites or contrast with similar tools, so it's left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive, so the safety profile is clear. The description adds behavioral context by specifying what is checked (SQL, page refs, missing items) and the output format (score and issues), which goes beyond the annotations and helps the agent understand the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action and purpose, and contains no redundant information. Every word adds value: what is validated, the specific checks, and the return format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one optional parameter, strong annotations, and an output schema, the description covers the essential aspects: purpose, scope, and return value. It does not enumerate every possible issue type, but the level of detail is sufficient for correct tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides a full description for the only parameter (app_id), including its default behavior ('Uses current session app if omitted'). With 100% schema coverage, the description does not need to add parameter details, and it does not, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Validate') and resource ('APEX app') and clearly states the scope ('check SQL, page refs, missing items') and return format ('score 0-100 + issues'). This distinguishes it from sibling validation tools like apex_health_check and apex_check_requirements by highlighting the scored output and specific checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to validate an APEX app before deployment or finalization, but it does not explicitly state when to use it instead of similar tools like apex_health_check or apex_check_requirements. No alternatives or exclusions are mentioned, so guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true and destructiveHint=false. The description adds essential behavioral context by clarifying that it logs PL/SQL without executing and returns the log when disabled. This goes beyond the annotations and clarifies the state-changing nature (readOnlyHint=false) without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the primary action and effect. Every word carries meaning, with no filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter toggle with an output schema present, the description adequately covers the core behavior, the condition for returning the log, and the mode's purpose. No additional details are necessary.
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 fully describes the single boolean parameter with a default value and clear explanation of true/false semantics. The description adds no significant meaning beyond restating the toggle behavior, so the score aligns with the high schema coverage baseline.
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 action: 'Toggle dry-run mode' with the specific resource (PL/SQL execution). It explains the effect (log without executing) and the return behavior (log when disabled), distinguishing it from siblings like apex_run_sql which actually execute code.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for previewing or testing PL/SQL without side effects, but it does not explicitly state when to use it over alternatives or provide context like 'use before executing SQL'. However, the functionality is self-explanatory enough for an agent to infer typical usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds the 'session' scoping and 'recent' filtering, but does not disclose return format or ordering; the output schema fills some of that gap, but the description itself adds minimal behavioral detail beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that avoids redundancy and immediately states the tool's purpose. It is appropriately sized for the simple read-only operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter list, full schema coverage, output schema presence, and strong annotations, the description provides sufficient context. It correctly scopes the log to the current session, which is the key contextual detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single 'limit' parameter, including a description and default value. The tool description does not add extra parameter context, but the schema already fully documents the parameter, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') with a clear resource ('audit log') and scope ('recent MCP operations in this session'). It clearly differentiates from sibling tools, which focus on building/editing APEX components rather than retrieving session logs.
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 context is clear: use this tool to retrieve audit log entries for the current MCP session. It does not explicitly list alternatives or exclusions, but no sibling tool serves a similar purpose, so the usage is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this a read-only, idempotent, non-destructive operation. The description adds context by specifying exactly what components are included (regions, items, buttons, processes), giving the agent a clearer sense of the response scope. It does not contradict 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 a single, well-structured sentence with no redundancy. It front-loads the action ('Get all components') and immediately clarifies scope, making it concise and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two well-documented parameters, an output schema present, and annotations covering safety. The description fully explains what the tool does and its scope, so no additional context is needed.
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 for both parameters (app_id and page_id), with clear descriptions. The tool description adds no additional parameter-level semantics, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and a clear resource ('all components on a page'), enumerating the component types (regions, items, buttons, processes). This distinguishes it from sibling tools like apex_list_regions, apex_list_items, and apex_list_processes, which target individual component types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a complete view of page components is needed, and the phrase 'all components' contrasts with sibling tools that list only one type. However, there is no explicit statement about when to use this tool versus alternatives, nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-destructive read operation. The description adds no extra behavioral context such as return format or ordering. Since annotations cover the safety profile, this is adequate for a simple 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 a single concise sentence that front-loads the action ('List all') and the object ('APEX applications'). No words are wasted, and the structure is immediately understandable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only list tool with an output schema present, the description is fully adequate. It clearly states the scope (workspace) and what is returned (all applications). No further context is needed; the output schema covers return value details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so there are no parameter semantics to explain. The baseline for 0 params is 4, and the description adds no unnecessary details about parameters. This is appropriate as the tool takes no arguments.
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 action ('List all'), the resource ('APEX applications'), and the scope ('in the workspace'). It is specific enough to distinguish from sibling list tools like apex_list_pages or apex_list_tables, which target different resource types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: if you want to see all applications in the current workspace, use this tool. However, it does not explicitly state when to prefer this over alternatives or provide exclusion criteria. The intended use is evident from the tool name and description, but no direct guidance is offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, fully covering the safety profile. The description adds no behavioral traits beyond the operation itself, which is already implied by 'List'. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, effective sentence, front-loaded with the verb and resource. It contains no extraneous words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool, the description, annotations, and schema are fully sufficient. An output schema exists, so return values are documented elsewhere. No critical context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both app_id and page_id having clear descriptions. The tool description adds no additional parameter meaning; it merely repeats the page scope already present in page_id. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List dynamic actions on a page of an existing app' clearly states the verb (List), resource (dynamic actions), and scope (page of an existing app). It distinguishes from sibling tools like apex_list_items and apex_list_processes by naming the specific component type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this tool to enumerate dynamic actions for a specific page. It does not explicitly state alternatives or when not to use, but the context is strong enough and the sibling list provides natural differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation as readOnly, idempotent, and non-destructive. The description adds 'all LOVs' and 'existing app', but does not detail pagination, error behavior, or permission requirements. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that wastes no words. It clearly states the verb and the resource without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with one required parameter, read-only annotations, and an output schema, the description is fully sufficient. An agent can unambiguously select and invoke this tool without additional behavioral detail.
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 provides 100% coverage for the only parameter, app_id, with its type and description. The description adds the context that the app must already exist, but this is not a significant parameter-level enhancement 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 uses the specific verb 'List' and clearly identifies the resource as 'LOVs (Lists of Values)' in an existing app. This distinguishes it from sibling tools like apex_add_lov (which creates) and apex_list_pages (which lists different entities).
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 (list all LOVs in an existing app) and implies the need for an app_id, which is sufficient for selecting this tool over alternatives. However, it does not explicitly state exclusions or mention specific alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by revealing the compound behavior: it adds both a FILE_BROWSE item and an after-submit process. It also explains the purpose of the process (storing uploads as BLOB), which adds context not present in the readOnlyHint=false or destructiveHint=false 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 a single, concise sentence that front-loads the action and purpose. Every word contributes value, with no filler or redundant phrasing.
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 (10 parameters, compound action), the description is adequately complete. It mentions the essential components (item + process) and the storage goal. The presence of an output schema and comprehensive parameter descriptions reduces the need for the description to explain return values or parameter formats.
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 covers all parameters with detailed descriptions (100% coverage), so the description does not need to add parameter semantics. The description itself mentions no parameter details, but the schema handles this dimension adequately, earning the baseline score.
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: 'Add a FILE_BROWSE item + after-submit process to store uploads as BLOB.' It uses a specific verb (Add) and a specific resource type (FILE_BROWSE item), distinguishing it from other add_* siblings like apex_add_item or apex_add_process.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: whenever file uploads need to be stored as BLOBs. It does not explicitly name alternatives or exclusions, but the context is unambiguous, and the combination of FILE_BROWSE + after-submit process makes its purpose distinct among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey read-only, idempotent, and non-destructive behavior. The description adds value by specifying exactly what is checked (connection, workspace, grants), which is useful context beyond the annotations. It does not describe error behavior or return structure, but output schema covers the return.
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 a single sentence with no wasted words. It clearly front-loads the verb and lists the key components, achieving maximum information density.
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 zero-parameter tool with an output schema, the description adequately captures the core purpose. It does not explain use cases or prerequisites, but those are not necessary for such a simple verification tool. The description is sufficient for an agent to understand what it does.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description meaningfully elaborates on what the tool verifies, which is the only semantically important aspect. No additional parameter details are 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 tool's purpose with a specific verb ('Verify') and three distinct resources (Oracle connection, APEX workspace, grants). This distinguishes it from sibling tools like apex_connect (connection only) and apex_check_permissions (grants only) by combining them into a single requirements check.
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?
No explicit guidance on when to use this tool versus alternatives is given. The context implies a pre-flight check before configuration or other operations, but this is not stated. Siblings like apex_health_check and apex_setup_guide are not mentioned as 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?
Annotations already declare idempotentHint=true and destructiveHint=false, so the description only needs to add context beyond that. It does add the 'Must be called first' sequencing behavior, which is useful. It doesn't provide details on connection lifecycle or failure modes, but given the simple nature of a connect call and existing annotations, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, the first clearly states the action and target, the second a critical sequencing note. No fluff, no repetition of schema information. Perfectly front-loaded and 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?
The tool has an output schema (not shown but indicated), so return values are presumably documented there. The description provides the crucial 'must be called first' context, which is essential for the agent's workflow. It doesn't mention prerequisites like environment variables, but those are already described in the schema defaults. For a connection tool, this is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents all 5 parameters with descriptions and defaults (100% coverage). The description itself adds no new parameter semantics; it just repeats the connect purpose. Therefore, baseline score of 3 is appropriate since the schema already 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: connecting to Oracle ADB via mTLS wallet. It includes a specific verb ('Connect'), a resource ('Oracle ADB'), and a key method ('mTLS wallet'). It also distinguishes itself by adding the sequencing instruction 'Must be called first', which sets it apart from all sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The instruction 'Must be called first' provides an explicit usage context, telling the agent to invoke this tool before other APEX operations. It doesn't explicitly mention alternatives or when not to use it, but for a connection prerequisite this is clear. A small deduction for not elaborating on whether this is required for every session or any error consequences.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false, destructiveHint=false, and idempotentHint=true, covering mutation safety and repeatability. The description adds meaningful context by specifying the types of issues addressed (grants, synonyms) and the 'auto-fix' nature. While it doesn't disclose every side effect, it aligns with annotations and contributes useful detail beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is a single, front-loaded sentence with no wasted words. It uses a clear verb 'Auto-fix' and parenthetical examples for specificity. Every word contributes meaning, making it highly concise 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 the tool has no parameters and an output schema exists, the description doesn't need to explain return values. It covers the core purpose and examples of issues. However, it could briefly mention when to run it (e.g., after apex_check_permissions) or what the output indicates, but these gaps are minor for a zero-configuration tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is 100% by default. Per the baseline for 0-param tools, a score of 4 is appropriate. The description doesn't need to explain parameters since there are none, and it doesn't attempt to add any parameter-related information.
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 function: 'Auto-fix common Oracle permission issues (grants, synonyms).' The verb 'fix' identifies the action, the resource 'permissions' defines the scope, and examples (grants, synonyms) add specificity. It also distinguishes itself from sibling apex_check_permissions by implying a corrective role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when permission issues exist, but it offers no explicit guidance on when to use this tool versus alternatives like apex_check_permissions. There is no mention of prerequisites, when not to use, or how it complements the check tool. Usage context is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide basic non-read-only, non-destructive flags. The description adds useful behavioral context by specifying the implementation method ('inline modal popup form') and the return value ('region_static_id for JS open'). It does not detail side effects or permissions, but for a create operation this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the primary action and key differentiator, followed by the return value. Every word earns its place; no fluff or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters, all described in schema, an output schema present, and annotations given, the description is relatively short but sufficient. It captures the essential purpose, placement, and return value. Missing explicit guidance on when to choose this over alternatives, but that is covered under usage guidelines.
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 all parameters are already documented with meanings and defaults. The description adds minimal parameter-level info beyond noting the feature of an inline modal. Baseline of 3 is appropriate since 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 uses a specific verb ('Create') and resource ('inline modal popup form'), and clearly distinguishes from separate page creation by saying '(no separate page)'. It also states the key return value (region_static_id for JS open), making the tool's purpose unambiguous even among many sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase '(no separate page)' provides clear context for when to use this tool—when an inline modal is desired rather than a dedicated page. It does not explicitly name alternatives or exclusions, but the context is sufficient for an agent to differentiate from related page/region creation 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?
Annotations already indicate the operation is idempotent and non-destructive. The description adds the behavioral detail that operations are queued for a single round-trip, implying the tool does not execute them immediately. This is useful context but not extensive; no contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the verb, and conveys both action and purpose without wasted words. Excellent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with output schema and annotations providing safety details, the description sufficiently conveys the core behavior and purpose. It could mention pairing with apex_commit_batch, but that is inferable from siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is trivially 100% covered. Description adds no parameter-specific meaning, but with no params, the baseline of 4 is appropriate.
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 'Start' and the resource 'batch mode', and explains the purpose: queue PL/SQL operations for a single DB round-trip. This distinguishes it from sibling tools like apex_run_sql or apex_commit_batch by focusing on the initiation of batching.
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: it's for starting batch mode to queue operations, implying it should be used when multiple operations need to be sent in a single round-trip. It does not explicitly exclude use cases or name alternatives, so it falls short of a 5 but earns a 4.
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:

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

Score Badge

Copy to your README.md:

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

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/TechFernandesLTDA/apex-mcp'

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