paperclip-mcp

Server Quality Checklist

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

Latest release: v0.1.0
Disambiguation4/5
Most tools have distinct purposes with clear descriptions and unique paths, but there are some legacy tools that redirect to correct paths and overlapping actions (e.g., export vs preview export) that could cause minor confusion.
Naming Consistency5/5
Tool names follow a highly consistent pattern: pc_verb_noun in snake_case. Even long names with hashes are predictable and follow the same structure.
Tool Count1/5
With 592 tools, the count is far too high for a well-scoped MCP server. While it reflects a comprehensive API, it overwhelms agents and goes well beyond the typical 3-15 tool guideline.
Completeness5/5
The tool set covers extensive CRUD and lifecycle operations for companies, agents, issues, projects, skills, tools, etc., leaving few obvious gaps for the domain of managing an agent platform.
Average 2.9/5 across 499 of 592 tools scored. Lowest: 1.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 9 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
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?
The description adds a line about the authorization class ('board_or_agent'), but no other behavioral traits beyond annotations. It does not disclose side effects, partial update behavior, or validation rules.
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 short (two sentences), but it omits necessary details. The second sentence is technical. While concise, it fails to convey essential information efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high complexity (nested objects, many parameters) and the existence of an output schema, the description is severely incomplete. It does not explain what an execution workspace update entails, leaving the AI with insufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of the parameters. The complex nested schema (including subfields like config, status, etc.) is left entirely undocumented, offering no help to the AI.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description repeats the title 'Update an execution workspace' without adding specifics. It does not detail what an execution workspace is or what aspects can be updated, making it nearly a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/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 indicate when to use this tool over alternatives, nor does it mention prerequisites or consequences of updating an execution workspace.
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. The description adds only an authorization class note but no details on side effects, state changes, or output schema behavior. Minimal value beyond structured data.
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 short but poorly structured; it repeats the title and adds a technical endpoint line that may clutter without adding clarity. It is concise but at the expense of usefulness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has nested objects, two required parameters, and an output schema, the description fails to explain the operation's context, what 'accept' entails, or how the output should be used. Highly incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain any parameters (selectedOptionIds, selectedClientKeys, path.id, path.interactionId). The agent receives no guidance on what to provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description repeats the title verbatim ('Accept an issue thread interaction') and adds a technical endpoint reference, but does not explain what 'accept' means in this context (e.g., accepting a suggestion, approving a change). It does not distinguish from sibling tools like reject or respond, lacking specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., reject, respond). No prerequisites, context, or conditions for use are provided.
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 claims to 'restore' but annotations indicate destructiveHint: true. This is a direct contradiction. Additionally, it does not explain side effects (e.g., whether the item appears again in inbox) or authorization implications beyond stating 'Authorization class: board_or_agent'.
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 very short (two sentences), with no fluff. However, it repeats the title and includes technical details that could be more integrated. It earns a 4 for conciseness but lacks structured information.
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 complexity of the API (nested objects, output schema) and the presence of closely related inbox tools, the description is insufficient. It does not mention the purpose of restoration, the effect on item visibility, or how the output schema relates to the 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 description adds the URL template but does not explain what companyId or itemKey represent beyond what the schema already provides. Schema coverage is 50%, but the description does not compensate by providing missing context for the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Restore an inbox dismissal or snooze', but the HTTP method is DELETE and annotations include destructiveHint: true, creating confusion. The purpose is unclear: does it restore or delete? It does not clearly define the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/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 pc_post_companies_by_company_id_inbox_dismissals (to dismiss) or pc_get_companies_by_company_id_inbox_dismissals (to list). No prerequisites or context for usage.
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 no behavioral context beyond annotations. It does not explain side effects, idempotency, or authorization nuances. Annotations indicate non-read-only and non-destructive, but the description doesn't elaborate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but not effectively concise; it omits essential information. It is under-specified rather than appropriately brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the input schema (nested objects, many parameters) and the existence of an output schema, the description is completely inadequate. It fails to explain the tool's purpose, parameters, or behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description provides zero information about the body parameters (driver, name, config, envVars, etc.). It adds no meaning beyond the schema structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Probe environment config' is vague and does not clarify what probing environment config means. It only restates the name and provides the HTTP method and path, but lacks a specific verb and resource explanation.
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 on when to use this tool versus alternatives like pc_post_environments_by_id_probe or pc_post_companies_by_company_id_environments. The description does not mention use cases 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?
Annotations already declare readOnlyHint=true, so safe read. Description adds HTTP method and authorization class, which is marginal. 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very short, but it's under-specified and not usefully concise. Every sentence is a restatement or technical detail without adding value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the multitude of cost report siblings and the complexity of the domain, the description fails to provide any meaningful context to differentiate the tool or explain its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention the single parameter (companyId) or provide any additional semantic meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description essentially restates the tool's title and HTTP method, without explaining what 'by-provider' means or how it differs from sibling cost report tools. It's a tautology.
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 on when to use this tool vs the many other cost report tools (by-agent, by-biller, etc.). Lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read, non-destructive write operation. The description adds authorization class and HTTP method, providing minimal behavioral context beyond annotations. No disclosure of side effects or what happens when fields are updated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise but incomplete. Two sentences provide no meaningful guidance. The first sentence is a tautology, and the second offers technical details but no user-oriented explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (many parameters, nested objects, output schema), the description is completely inadequate. It fails to explain what updates are possible, how to construct the body, or what the response contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the tool description provides no explanation of any parameters. The body and path parameters have complex fields (e.g., cwd, metadata, runtimeConfig) with no descriptions in schema or text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description repeats the title 'Update a project workspace' verbatim, adding only HTTP method and authorization class. It does not distinguish this update operation from sibling tools like create or delete project workspace.
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 on when to use this tool versus alternatives (e.g., when to update vs create/delete). The description lacks any context about prerequisites or appropriate use cases.
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 and destructiveHint=false, so the description adds authorization class ('board_or_agent') but does not disclose other behavioral traits like idempotency, error behavior, or side effects. The description provides minimal additional value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) but under-specifies important aspects. It is not concise in the sense of being informative; it is merely brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a complex input schema with nested objects and enums, but the description provides no context about what the tool returns, how to structure the body, or when to use optional fields. The existence of an output schema is noted but the description does not leverage it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain any of the parameters (companyId, kind, name, slug, color, parentId, position) or their roles. The agent must rely solely on the schema, which lacks semantic context.
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 states 'Create a folder' which matches the title, but it does not differentiate from sibling tools like 'pc_post_companies_by_company_id_folders_ensure_my' which also creates a folder. The HTTP path and authorization are mentioned, but the specific purpose among similar folder creation tools is unclear.
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 on when to use this tool versus alternatives such as 'ensure_my' or 'patch' or 'delete' folder tools. The description lacks any contextual cues 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?
Annotations already indicate a write operation (readOnlyHint: false), and the description adds only the authorization class ('board'). It does not disclose what happens during import (e.g., creation vs. upsert), whether remote provider configuration is needed, or any side effects. The description adds minimal behavioral context 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (three lines) but lacks substance. While conciseness is valuable, the content is too sparse to be useful. Important operational details are omitted, making it more under-specified than appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the input (nested required objects, provider configuration, multiple secrets) and the presence of many sibling tools, the description is severely incomplete. It does not explain the purpose of providerConfigId, the structure of secrets, or how remote import differs from local creation. An output schema exists but is not referenced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the tool description contains no explanation of the parameters (path.companyId, body.providerConfigId, body.secrets). The agent must infer meaning solely from parameter names and types, which is insufficient for correct usage.
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 states 'Import remote secrets' which identifies the verb and resource, but it does not clarify what 'remote secrets' are or how they differ from other secret operations. The added API path and auth class are technical details, not functional clarification. Among sibling tools like pc_post_companies_by_company_id_secrets (create secrets) and pc_post_companies_by_company_id_secrets_remote_import_preview, the purpose is somewhat distinguishable but not explicitly scoped.
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 pc_post_companies_by_company_id_secrets or the remote import preview. It lacks any context about prerequisites, use cases, or exclusions. The agent receives no help in deciding between similar 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 adds minimal behavioral context beyond the title. Annotations indicate the tool is not read-only and may have side effects (openWorldHint=true), but the description does not explain the nature of those side effects, whether it starts an async job, or what gets mutated. It carries some burden but fails to disclose key behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but at the expense of completeness. It is not concise in a helpful way; it repeats the title and adds boilerplate HTTP info. There is no meaningful structure that aids understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (2 required parameters with nested objects, output schema exists but unused), the description is severely incomplete. It misses all parameter semantics, output expectations, and operational details like whether the scan is synchronous or asynchronous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description must explain parameters. It does not mention any parameter names, types, or purposes. The 'body' parameter is complex with nested selections, but the description provides zero semantic information.
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 title and first line state 'Scan project for skills', which indicates the tool's main action. However, the description does not elaborate on what scanning means—e.g., whether it analyzes files, updates skill data, or returns a report. It does not distinguish this from sibling tools like pc_post_companies_by_company_id_skills_import.
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 on when to use this tool versus alternatives. No prerequisites, context, or exclusions are mentioned. The technical HTTP details do not help an agent decide when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions the HTTP method and authorization class, but does not disclose important behavioral traits such as whether partial updates are allowed, if the operation is idempotent, or any side effects. Annotations already indicate it is not read-only, but the description adds little beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences), but the brevity comes at the cost of missing critical information. It repeats the title and includes a technical detail (HTTP path and authorization class) without being concise in a helpful way.
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 complexity of the input schema with multiple optional fields and nested objects, the description is incomplete. It does not explain the purpose of the body parameters, the semantics of status values, or the effect of updating a user secret, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should explain parameters. It does not mention any of the body fields (value, status, externalRef, providerConfigId, providerVersionRef) or path parameters (companyId, secretId), offering no guidance on what values are expected or valid.
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 restates the title 'Update my user secret value' and adds the HTTP method and path. It clarifies the verb and resource but does not differentiate from sibling tools like create, get, or delete user secrets.
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 pc_post_companies_by_company_id_me_user_secrets (create) or pc_delete_companies_by_company_id_me_user_secrets_by_secret_id (delete). The description lacks context for when updating 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?
Annotations already indicate read/write and non-destructive nature. The description only adds 'Authorization class: board', which is minimally informative. It does not clarify behavior on duplicate creation or other side effects, so little value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) but lacks essential detail. It is concise but at the expense of completeness, making it insufficiently informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/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 two complex parameters (nested objects), the description fails to describe inputs, usage context, or behavioral details. It is incomplete for effective tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain parameters but does not. No info about 'value', 'definitionId', 'companyId', or other fields is provided, leaving the agent unable to understand their meaning.
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 creates a user secret value for the current user, using the HTTP method and path. The title and description together convey the verb and resource. It distinguishes from sibling tools like get, patch, and delete. However, it could be more explicit about what a 'user secret value' is.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/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 prerequisites, such as having a user secret definition, nor does it explain differences from similar operations like patching or deleting.
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, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds no behavioral context beyond these annotations. It does not disclose that authorization class 'board' is required, nor does it mention potential side effects, rate limits, or what happens if the preview fails. The description fails to add value 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences), but conciseness comes at the cost of completeness. While it is efficient in length, it sacrifices necessary detail about purpose, parameters, and behavior. A tool description should balance brevity with informativeness; this one leans too far toward brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 main parameters (path and body) with nested fields, a total of 5 sub-parameters, and an output schema, the description is woefully incomplete. It does not explain what the operation returns, how pagination works, or the significance of providerConfigId. The agent cannot effectively use this tool without additional external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions exist in the schema. The tool description provides no information about the parameters (providerConfigId, query, pageSize, nextToken). The agent must guess their meanings from names alone. This is a significant gap as the description does not compensate for the lack of schema documentation.
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 title and description state 'Preview remote secret import', which gives a general purpose. However, the description is extremely terse, consisting only of the HTTP method and path. It does not explain what 'preview' entails—whether it returns a list of available secrets, validates configuration, or something else. This vagueness makes it difficult for an agent to understand the tool's exact function.
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. Notably, there is a sibling tool 'pc_post_companies_by_company_id_secrets_remote_import' that likely performs the actual import, but no distinction is made. The agent is left to infer usage context without explicit help.
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 says 'Test tool policy decision', implying a non-destructive evaluation, but annotations set readOnlyHint=false (contradiction). The description does not clarify whether the test creates side effects (e.g., audit logs) or is purely a simulation. This contradicts annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (two lines), but it is under-specified rather than concise. It sacrifices necessary detail for brevity, failing to add value beyond the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex input schema (2 required top-level parameters with deep nesting) and no parameter documentation, the description is completely inadequate. Even with an output schema, the input guidance is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description provides no explanation of the 'body' parameter's complex nested fields (actor, request, runContext, etc.). The agent must rely solely on the schema, which lacks descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The title and description clearly state 'Test tool policy decision' and provide the HTTP method and path, which distinguishes it from sibling tools like creating or reordering policies. However, it lacks specificity about what 'test' means (e.g., dry-run vs. actual creation).
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 pc_post_companies_by_company_id_tools_policies or pc_post_companies_by_company_id_tools_policies_reorder. It does not mention scenarios 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 indicate readOnlyHint=false and openWorldHint=true, but the description adds no detail about side effects, authorization requirements beyond 'board_or_agent', or what happens during control. The description does not meaningfully extend annotation information.
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?
Description is very short (two sentences), but it is under-informative. While concise, it sacrifices clarity and completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (2 required params, nested objects, output schema exists), the description is extremely incomplete. No explanation of action values, body fields, or response meaning.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% - description does not reference any parameters. The two required parameters (path with id and action, body with serviceIndex, runtimeServiceId, workspaceCommandId) are completely undocumented in the description.
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 says 'Control a runtime service in a workspace', which is a verb+resource but vague. It does not specify what 'control' entails (start, stop, etc.). It distinguishes from sibling 'pc_post_execution_workspaces_by_id_runtime_commands_by_action' which deals with commands, not services, but the distinction is implicit.
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 on when to use this tool vs alternatives. No prerequisites, context, or exclusions provided.
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, non-destructive mutation. The description adds no behavioral details (e.g., side effects of creating a hold, state changes). 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (one line) but at the cost of informative content. It is front-loaded but lacks structure; could be improved with bullet points or expanded context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex schema (nested objects, enums), output schema presence, and no description of return values or operational context, the description is severely incomplete. The agent lacks understanding of what tree holds are and how they work.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%; the description adds no meaning for any parameter. The complex body schema (mode, reason, metadata, releasePolicy) is left entirely to the agent to interpret from the raw schema. This is a significant gap.
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 states it creates an issue tree hold, specifying the verb and resource. However, it does not explain what a tree hold is or how it differs from related hold operations (e.g., releasing a hold). The minimal phrasing is adequate but lacks distinguishing context.
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 on when to use this tool vs alternatives like pc_post_issues_by_id_tree_holds_by_hold_id_release. Authorization class is mentioned but no explicit when/when-not advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds the HTTP method (GET) and authorization class ('board_or_agent'), which is useful context beyond annotations. However, it does not describe the response format or any specific behaviors like pagination or error conditions, keeping the transparency moderate.
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 short (two sentences) but the first sentence is redundant with the title. It is not overly verbose, yet every sentence does not earn its place—the endpoint and auth info add value, but the repetition is unnecessary.
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 complexity (nested input object, output schema, many sibling tools), the description is incomplete. It does not explain what the status represents, what the output contains, or how to interpret the result. The presence of an output schema does not excuse the lack of context about the tool's purpose and typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage—no parameter descriptions within the schema. The tool description does not explain the meaning of 'companyId' or 'key' beyond their presence in the endpoint path. Given the low schema coverage, the description should compensate but fails to do so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description repeats the tool's title and name ('Get built-in agent bundle status'), which is a tautology. It adds the HTTP endpoint but does not explain what 'built-in agent bundle status' means or how it differs from similar tools like pc_get_companies_by_company_id_built_in_agents (list) or pc_post_companies_by_company_id_built_in_agents_by_key_reconcile (reconcile).
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 mentions it's a GET operation with 'board_or_agent' authorization, but does not state prerequisites, when not to use it, or compare with sibling tools for built-in 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?
Annotations already indicate read-only, idempotent, non-destructive. Description adds HTTP method and authorization class, which provides some additional context but does not disclose behavioral traits beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short but fails to convey essential information. Conciseness is not accompanied by completeness; critical details are missing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/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 a nested structure, but the description provides no context about what window-spend means, what the response contains, or any usage hints. The description is grossly inadequate for effective agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning to the lone parameter (companyId). The parameter is merely listed without any explanation of its role or constraints.
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 states it is a cost report for window-spend, but does not explain what 'window-spend' refers to or differentiate it from other cost report tools among the many siblings.
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 on when to use this tool versus other cost reports (e.g., costs_summary, costs_by_agent). No context about prerequisites or typical use cases.
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 mutability (readOnlyHint=false). The description adds 'Authorization class: board_or_agent', which is a behavioral constraint not in annotations. However, it does not disclose whether updates are partial or full, what side effects occur, or any other behavioral nuances.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two lines) but this is under-specification rather than conciseness. The minimal text does not earn its place because it omits critical information about parameters and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high complexity of the input schema (many nested objects) and the presence of an output schema, the description is completely inadequate. It does not explain return values, required fields, or any operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain any of the many input parameters. Despite a complex schema with nested objects, the description offers no hints about how to use fields like 'name', 'status', or 'runtimeConfig'.
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 title and description state 'Update an agent', which is clear as a verb+resource pairing. However, among many agent-related sibling tools (e.g., pc_patch_agents_by_id_permissions, pc_patch_agents_by_id_instructions_path), the description does not differentiate what specific agent attributes this tool updates, making it vague.
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 pc_patch_agents_by_id_permissions or pc_post_agents_by_id_*. There is no mention of prerequisites, context, or exclusion criteria.
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 it is not read-only, not destructive, and not idempotent. The description adds authorization class ('board_or_agent') but does not explain behavioral effects like state changes or side effects of waking an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at two sentences, with no redundant information. However, it could benefit from a bit more substance without losing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has multiple parameters, nested objects, and enums, the description is severely lacking. It does not explain required fields, parameter purposes, or what happens when the tool is called. The presence of an output schema does not excuse the lack of input context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description is entirely responsible for explaining parameters. It provides no information about the 'body' fields (source, triggerDetail, reason, etc.) or the required path 'id'. The agent must rely solely on parameter names and enum values, which is insufficient.
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 states 'Wake up an agent' which is a clear verb+resource pair. However, it does not distinguish from sibling tools like 'resume' or 'pause', leaving ambiguity about when to use this specific action.
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 pause, resume, or terminate. The description lacks context on prerequisites or appropriate scenarios.
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 and destructiveHint=false, meaning it modifies something but is not destructive. However, the description adds no behavioral details such as what happens to the approval state, who is notified, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) but lacks essential information. It is concise but at the expense of completeness, making it minimally acceptable.
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, the description fails to explain the tool's purpose and parameters sufficiently. Given the many sibling approval tools, the agent lacks context to choose and use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has two required parameters (path.id and body.payload) with 0% schema description coverage. The description provides no explanation of what 'payload' should contain or how 'id' is used. This is a significant gap for correct invocation.
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 states 'Resubmit an approval' which is a verb+resource but does not clarify what resubmitting means in the context of approvals. Siblings include approve, reject, request_revision, so resubmit likely follows a revision, but this is not made explicit.
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 like pc_post_approvals_by_id_approve or pc_post_approvals_by_id_reject. The description does not specify prerequisites or typical scenarios.
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 write operation (readOnlyHint=false) and non-destructive (destructiveHint=false), but the description adds no behavioral context beyond the API path and authorization class. No contradictions, but no added value.
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 brief (two sentences), but its brevity sacrifices substance. It could include essential parameter details 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?
Despite having an output schema and complex nested parameters, the description offers no context about the activation process, prerequisites, or return values. It is insufficient for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should explain parameter meanings. It fails to mention any of the four parameters (connectionId, runId, companyId, entityType) or their roles, leaving the agent with only the schema.
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 states the action ('Activate cloud upstream push run entities') but does not explain what 'activate' means in this context. It distinguishes from siblings by specifying activation, but the purpose remains vague without further 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 use this tool versus alternatives like creating or previewing push runs. The description lacks any contextual advice 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 readOnlyHint=false and destructiveHint=false, but description does not clarify whether preview is safe or has side effects. The openWorldHint=true further needs clarification. The description adds only the underlying API path and auth class, which are not in the structured fields but do not disclose behavioral traits like mutability or cost.
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?
Two sentences, very concise. However, the first sentence is a near-verbatim repetition of the title, and the second sentence is implementation detail (Paperclip operation, auth class) that may be irrelevant for an agent. It is not front-loaded with key agent-facing information.
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 two-param tool with output schema and annotations, the description is inadequate. It does not explain the purpose of preview, what the output represents, or how to interpret results. Missing context about cloud upstreams and why preview is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Parameter schema has 0% description coverage, and the description provides no information about the two required parameters (connectionId and companyId). The agent has no guidance on what values to provide or how they affect the preview.
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 states 'Preview a cloud upstream push run' which identifies the resource and verb, but does not clarify what 'preview' means in this context (e.g., dry-run, simulation, or read-only check). It distinguishes from the sibling `pc_post_cloud_upstreams_by_connection_id_push_runs` only by the word '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 on when to use preview vs the actual push run or other tools. It does not mention that a preview should be used before executing a push run, nor any conditions 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 already indicate it's not read-only (readOnlyHint=false) and not destructive (destructiveHint=false), but the description adds only an authorization class ('board_or_agent') and HTTP method, not behavioral details like side effects, whether it modifies existing data, or what the return value represents. For a mutation tool, more behavioral context is needed.
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 short (two sentences) but wastes space on internal metadata (Paperclip operation, authorization class) rather than agent-facing guidance. It is concise but not well-structured for agent consumption.
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 complex input schema with nested objects and many options, the description is insufficient. It does not explain the overall import process, prerequisites, or how to construct the 'body' parameter. The presence of an output schema does not compensate for missing operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no parameter explanations. It does not clarify the roles of 'source', 'target', 'include', or other nested fields, leaving the agent to guess from the schema structure alone.
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 states 'Apply a company import' but does not explain what 'apply' means in this context (execute a previously previewed import? perform an import from scratch?). It does not distinguish from sibling tools like pc_post_companies_import_preview or pc_post_companies_by_company_id_imports_apply, leaving the agent to infer the difference.
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 on when to use this tool versus alternatives. The description only mentions it's a 'legacy route' but doesn't specify the preferred modern alternative or criteria for choosing this one.
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 the exact HTTP method and path, and authorization class, which are not in annotations. However, it does not disclose any behavioral traits such as side effects, whether it modifies state, or what the preview returns. Annotations already indicate readOnlyHint=false, but the description fails to elaborate on the mutation semantics or any other significant behaviors beyond what the endpoint implies.
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 short (two sentences) and avoids unnecessary verbiage. However, it redundantly restates the title as the first sentence, and the structure does not lead with a clear purpose statement. While concise, it sacrifices informativeness and logical organization.
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 one parameter with constraints (min/max lookbackHours) and an output schema, the description is critically incomplete. It does not explain what the tool does in context (e.g., what 'issue graph liveness auto-recovery' means), how the parameter affects output, or what the response contains. An agent would struggle to select or use this tool correctly without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention the single parameter 'lookbackHours' or its purpose (e.g., what it controls, default values, or impact on results). The description's silence on parameters leaves the agent with no semantic understanding of how to use the input, severely hindering correct invocation.
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 states the tool 'previews issue graph liveness auto-recovery', providing a verb and resource. However, the meaning of 'issue graph liveness auto-recovery' is obscure, and the description does not clarify what this preview entails or how it differs from the similarly named sibling tool (e.g., pc_post_instance_settings_experimental_issue_graph_li_f0f6648423). The purpose is vague and lacks sufficient context for an agent to understand the tool's functionality.
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. The description mentions 'Preview' and provides the API endpoint and authorization class, but does not explain the conditions under which previewing is appropriate, prerequisites, or when to avoid it. The sibling list includes many tools, but no differentiation or usage context is provided.
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 write operation (readOnlyHint false). The description adds no additional behavioral context, such as whether the thread is created immediately, what happens to existing threads, or if document lock is required.
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 very short with no fluff. The inclusion of the HTTP method and authorization class provides some value. However, the extreme brevity limits its usefulness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with many nested required parameters and an output schema, the description is completely inadequate. It omits any explanation of the request body structure, response format, or required fields beyond the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of the complex nested parameters (body with selector, quote, position, etc.). The agent has no way to understand how to construct the request from the description.
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 states 'Create a document annotation thread' which is a specific verb and resource. However, it fails to distinguish from the sibling tool 'pc_post_issues_by_id_documents_by_key_annotations_by_47c99d67c5' which likely also creates an annotation (possibly a reply). Without clarification, the agent may confuse the two.
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 on when to use this tool versus alternatives like the GET or PATCH annotation tools. The only extra info is the authorization class, which is not usage advice.
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 read-only, idempotent, and destructive hints are all false, but the description adds only the authorization class (public). No behavioral details such as side effects, state changes, or failure modes are disclosed, adding minimal value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief (two sentences), but it lacks essential details. It is front-loaded with the operation path and auth class, but the brevity comes at the cost of clarity and completeness.
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 nested objects, the description does not explain the tool's overall function beyond 'handle requests'. It fails to specify what the request body should contain, how gatewayId is used, or what the response represents, leaving significant gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no explanation of the parameters. The 'body' and 'path' objects are mentioned only by name, leaving the agent without guidance on their content or purpose.
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 states 'Handle named MCP gateway protocol requests' and provides the HTTP method and path, but it does not clarify what 'handle' means (e.g., create, invoke, or forward). It vaguely distinguishes from sibling GET tool by mentioning POST operation, but the purpose remains ambiguous.
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 on when to use this tool versus alternatives (e.g., the GET version or other gateway tools). No context on prerequisites, use cases, or exclusions 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, destructiveHint=false. The description adds HTTP method (GET) and authorization class, but no further behavioral details (e.g., pagination, data freshness). Acceptable given annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is overly terse, consisting of a title repetition and HTTP metadata. While concise, it sacrifices essential information that would aid tool selection and invocation.
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, the description does not mention what data the report returns, nor does it differentiate from sibling cost breakdown tools. Incomplete for an AI agent to understand its role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no explanation of the required 'companyId' parameter. It only appears in the path example without additional context, leaving the agent uninformed about its semantics.
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?
Title and description indicate 'Cost report: by-biller' and the HTTP path, vaguely suggesting retrieval of costs grouped by biller for a company. However, it does not clearly state the action (e.g., 'Retrieve cost breakdown by biller') and fails to distinguish from sibling cost 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 on when to use this tool versus alternatives like cost by agent, provider, or project. With many cost report siblings, the description offers no 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 description adds very little beyond the annotations. It discloses that this is a POST operation and the authorization class, but fails to explain behavioral traits such as side effects, idempotency, or what happens on success/failure. Since annotations are present (readOnlyHint: false indicating mutation), the description's contribution is minimal, and key behavioral context is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences), but it is under-specified rather than concise. It wastes space by repeating the title and adding a raw API path, which is already implicit in the tool name. Critical information about parameters and usage is missing, making the description ineffective despite its brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with nested parameters and an output schema, the description is severely incomplete. It does not explain the provisioning process, expected input values, or the structure of the response. Given the complexity and the presence of an output schema, the description fails to provide essential context for proper invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has two required parameters (body and path) with no individual descriptions (0% coverage). The description entirely omits parameter details, such as the meaning of 'adapterType', 'adapterConfig', or 'budgetMonthlyCents' in the body, or the 'key' and 'companyId' in the path. An agent would have no guidance on how to populate these fields correctly beyond the schema structure.
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 'Provision a built-in agent' which is a clear verb+resource combination. It also provides the HTTP method and path, which adds specificity. However, it does not explain what 'provision' entails, leaving some ambiguity about the exact action performed. Still, it is sufficiently clear for an agent to understand the general purpose.
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 prerequisites, such as whether the agent must exist or be in a certain state, nor does it contrast with other built-in agent operations like reconcile or reset. An agent would have to infer usage from the tool 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?
The description states 'ensure' implying idempotent creation, but annotations set idempotentHint=false, creating a contradiction. Beyond the title and auth class, no additional behavioral traits (e.g., what happens if folder exists, side effects) are disclosed. The annotations already provide some info, but the description 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) but the first sentence redundantly repeats the title. It lacks structure and leaves out critical information, making it under-specified rather than concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With two parameters (including nested objects), an output schema, and sibling tools, the description is severely incomplete. It does not explain the return value, the 'ensure' semantics, or the meaning of the slug. The agent has insufficient context to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no explanation of the two required parameters (path.companyId and body.slug). The optional slug parameter's purpose and format are not described, leaving the agent with only the schema constraints.
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 title and first sentence clearly state the tool's purpose: ensuring the current user's personal skill folder exists. However, it does not differentiate from sibling folder tools like pc_post_companies_by_company_id_folders, which creates a folder. The term 'ensure' implies idempotent behavior but is not explicitly contrasted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs. alternatives (e.g., creating a folder). The description mentions authorization class but does not specify 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 indicate this is not read-only (readOnlyHint false) and not idempotent, but the description adds no behavioral details beyond 'Authorization class: board'. It does not explain what happens to the original policy, side effects, or response characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief (3 short sentences) but omits critical information such as parameter meanings and usage context. Conciseness should not come at the expense of completeness; here it is under-specified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 required parameters, nested objects, and a non-trivial action (duplicate), the description fails to cover what the tool returns, the meaning of parameters, or any constraints. The presence of an output schema is not leveraged.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description provides no explanation of parameters (body.name, path.companyId, path.policyId). The agent cannot infer that 'name' is required for the duplicate's new name. This severely hinders correct invocation.
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 title and description clearly state 'Duplicate a tool policy', indicating the action of creating a copy. This distinguishes it from sibling tools for creating, deleting, or patching policies. However, it lacks specifics on what duplication entails.
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 on when to use this tool vs alternatives, no prerequisites (e.g., existing policy), and no exclusions. The description only mentions the endpoint and authorization class, leaving usage context entirely 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?
The description claims it's a 'Get' operation, but annotations set readOnlyHint=false, creating a contradiction (annotation_contradiction=true). The description does not explain side effects, idempotency, or authorization beyond a cryptic 'Authorization class: board'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very terse (22 words), but under-specification makes it nearly useless. It sacrifices completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/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 nested parameters, the description provides no information about response format, the purpose of body.params or companyId, or how the tool fits into the broader workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fails to explain any of the 2 parameters (path, body). It only repeats the endpoint structure, adding no semantic value over 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 title and description clearly state 'Get plugin data by key (URL-keyed bridge)' and provide the endpoint path, making the retrieval purpose evident. It distinguishes from sibling 'pc_post_plugins_by_plugin_id_bridge_data' by focusing on key-specific data.
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 'pc_post_plugins_by_plugin_id_bridge_data'. There is no mention of prerequisites, context, 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 adds no behavioral details beyond what annotations already provide. It mentions 'Authorization class: board' which hints at permissions, but does not disclose side effects (e.g., updating the profile state) or explain the consequences of 'allow' vs 'keep_blocked' decisions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is too concise, sacrificing essential information. Only two sentences that repeat the title and provide the HTTP path, without explaining what the tool actually does or how to use it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (nested objects in input, output schema present, many sibling tools), the description is severely incomplete. It fails to describe the decisions array, output structure, or relationship to other tool profile endpoints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no explanation of the required parameters (profileId and decisions array). It does not describe the structure of decisions (catalogEntryId, enum allow/keep_blocked) or the format of the path parameter.
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 title and description clearly indicate the tool is for reviewing new catalog tools for a profile. The inclusion of the HTTP method and path provides additional context. However, it does not differentiate among many sibling tools that also operate on tool profiles (e.g., patching, deleting, duplicating).
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 lacks any guidance on when to use this tool versus alternatives. No mention of prerequisites, typical workflow steps (e.g., first fetch new tools with another endpoint), 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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false, implying a safe write operation. The description adds the authorization class ('board_or_agent') and HTTP method, but fails to disclose whether the PUT replaces or appends installs, or any other behavioral details 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but inefficient: the first line repeats the title verbatim, and the remaining lines provide only endpoint and auth class. No structured breakdown of behavior, parameters, or examples. Every sentence should add value, but the repetition wastes space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (2 required parameters, nested arrays, output schema), the description is severely inadequate. It does not explain the effect of the operation, the meaning of the parameters, or any edge cases. With no schema description and minimal text, the agent lacks critical context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not mention any parameter names, purposes, or constraints. The schema defines 'connectionId', 'installs' array with 'targetType' and 'targetId', but the description provides zero semantic context for these 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 title and description state 'Sync tool connection installs', and the endpoint URL indicates a PUT operation to update installs for a given connection. This clearly conveys the action of modifying the installation list, but the term 'sync' is ambiguous and does not explicitly specify whether it replaces or merges installs. However, it is sufficiently clear for an agent to infer the basic purpose.
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. There is a sibling GET endpoint for retrieving installs, but no comparison or context for when to use PUT vs GET. No prerequisites or alternatives 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?
Annotations already declare readOnlyHint true and destructiveHint false. The description adds the authorization class ('board_or_agent') and confirms GET request, which is consistent. No contradiction, but little extra value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is very short (3 lines) and concise, but at the cost of informativeness. It is not wasteful, but could be improved with more relevant details.
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 complexity (many siblings, output schema exists), the description is insufficient. It does not describe what the output contains, how finance-events differ from other cost reports, or any filtering capabilities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has one required parameter (path.companyId) with 0% description coverage. The description does not mention the parameter, its format, or purpose. Complete lack of parameter guidance.
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 states it is a 'Cost report' for 'finance-events' and shows the HTTP method and path, but does not explain what finance-events are or differentiate from many similar cost endpoints (e.g., costs_summary, costs_finance_by_biller). Purpose is somewhat clear but lacks specificity.
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 on when to use this tool versus alternatives. Given many cost-related siblings, the agent has no basis to choose this over others like costs_finance_by_biller or costs_finance_by_kind.
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 readOnlyHint, idempotentHint, and destructiveHint false. The description adds the authorization class 'board_or_agent', which is useful beyond annotations, but it does not disclose other behavioral traits like rate limits, data scope, or pagination.
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 concise (two sentences), but the first sentence unnecessarily repeats the title. While short, it could be more informative without adding length, e.g., by explaining the report contents.
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 large number of sibling cost tools, the description does not clarify what 'summary' entails or how this tool fits into the cost report ecosystem. An output schema exists, but the description does not hint at the return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one required parameter (companyId) with no description. Schema description coverage is 0%, and the description does not compensate by explaining the parameter's meaning or format. This is a significant gap.
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 states 'Cost report: summary' and the HTTP endpoint, implying it retrieves a summary cost report for a company. However, it does not clearly distinguish this tool from sibling cost reports like 'by agent' or 'by provider', leaving ambiguity about what 'summary' specifically means.
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 cost-related tools (e.g., pc_get_companies_by_company_id_costs_by_agent). No prerequisites, exclusions, or context for usage are provided beyond the endpoint and authorization class.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds authorization class and HTTP method, providing some extra behavioral context but not rich details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise (two lines) but at the expense of clarity and completeness; lacks structure and fails to convey essential information.
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 annotations and an output schema, the description is too sparse to provide sufficient context for correct usage, especially given the large number of sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'companyId' parameter or the path structure. The tool has only one parameter, but the description adds no semantics beyond the schema.
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 repeats the title 'Get environment capabilities' and adds the HTTP method/authorization class, but does not clarify what 'capabilities' are or differentiate it from sibling tools like pc_get_companies_by_company_id_environments.
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 on when to use this tool vs alternatives; the description lacks context about appropriate usage scenarios 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?
Annotations already declare the tool as readOnly, idempotent, non-destructive, and openWorld. The description adds the HTTP method (GET) and authorization class (board_or_agent), which is helpful but minimal. It does not disclose error handling, rate limits, or pagination behavior. With annotations covering safety, the description adds moderate value.
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 (three lines) and includes the endpoint and auth class. However, it is too minimal and omits essential information. Conciseness is good, but the lack of substance reduces its effectiveness.
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 (single parameter, read-only, but search functionality) and the presence of an output schema, the description is incomplete. It does not explain what data is being searched, how results are structured, or any search query capabilities. The context is insufficient for an agent to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description contains no information about parameters. The input schema has one parameter (path with companyId) but has 0% schema description coverage. The description fails to explain what companyId represents or how to format it, leaving the agent to infer from the name.
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 states 'Search company data' and the endpoint path indicates a search per company ID. However, it does not specify what kind of search (e.g., full-text, filtered) or differentiate from similar sibling tools like pc_get_companies_by_company_id or pc_get_companies_by_company_id_search_extract. The purpose is vaguely clear but lacks specificity.
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. There is no mention of when to use search vs. listing all companies or retrieving a single company. The description offers no context for tool selection.
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 claims a read-only GET operation, but annotations set destructiveHint=true, creating a contradiction. No additional behavioral context is provided, such as whether the operation might incur costs or have side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short but under-specifies important details. It merely repeats the title and adds API path/auth info, leaving out usage context and parameter guidance.
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, the description does not explain what the blast radius result contains. For a potentially destructive assessment tool, more context is needed to ensure proper interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'path.id' (string) has 0% schema coverage, and the description adds no meaning about its format, expectations, or role in identifying the environment.
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 name and description clearly state the purpose: retrieving the delete blast radius of an environment. The HTTP method and path are provided, making it distinct from sibling tools like pc_get_environments_by_id or pc_delete_environments_by_id.
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 does not specify when to use this tool versus alternatives. It lacks guidance on prerequisites, such as needing to first call pc_get_environments_by_id, or when to consult before performing a delete.
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 read-only, idempotent, non-destructive behavior. The description adds only the HTTP method and authorization class, which are redundant given annotations. No additional behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) but not wasteful. However, it is too brief to provide meaningful guidance, making it minimally adequate.
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 low complexity (one parameter, annotations present, output schema exists), the description still fails to define what an execution workspace is or how the tool fits into the broader system. The output schema is present, so return values need not be described, but the purpose and usage context are lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0% description coverage. The description does not explain the path.id parameter, leaving the agent with no guidance on what value to supply. This is a critical gap for such a simple parameter.
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 verb 'Get' and resource 'execution workspace', and provides the API endpoint. However, it does not explicitly differentiate from sibling tools like pc_get_companies_by_company_id_execution_workspaces, though the name and endpoint imply a single resource by ID.
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 on when to use or alternatives. The description mentions authorization class but lacks context about prerequisites, typical scenarios, or when not to call this tool.
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 and destructiveHint=false. The description adds only the authorization class ('board_or_agent') and the endpoint, which provides minimal behavioral context beyond the annotations. No mention of pagination or filtering 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) and front-loaded, but it lacks essential parameter and usage details. It is concise but under-specified.
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 simplicity (one parameter, read-only list), the description should still mention what the returned issues contain, any default sorting, or pagination. The existence of an output schema mitigates some concerns, but the description itself is insufficient for complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter runId has no description in the input schema (0% coverage) and the tool description does not explain its purpose, format, or how to obtain its value. This is a critical gap for correct usage.
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 'List issues for a heartbeat run', which clearly identifies the verb and resource. However, it does not explicitly distinguish from sibling tools like pc_get_heartbeat_runs_by_run_id_events, though the resource (issues) is distinct enough.
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 the HTTP method and path but offers no guidance on when to use this tool versus alternatives, such as pc_get_issues_by_id_runs or pc_get_heartbeat_runs_by_run_id. No prerequisites or context for invocation are 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 already provide readOnlyHint (true), destructiveHint (false), idempotentHint (true), and openWorldHint (true). The description adds minimal behavioral context beyond the HTTP method and authorization class, which are implementation details. It does not disclose any side effects, permissions, or limitations.
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 concise at two sentences, but it is under-specified. It front-loads the purpose but does not earn its place fully as it omits important details like parameter explanation. It could be slightly expanded without becoming verbose.
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 presence of an output schema, return values are not needed, but the description lacks context about what work products are and how they relate to issues. The single parameter (id) is not explained, and the tool's purpose within the broader issue management domain is unclear. More context would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter (path with id), but schema description coverage is 0%. The description does not explain what the id parameter represents (the issue ID) or how to use it. This leaves the agent without guidance on providing the correct input.
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 'List issue work products' clearly indicating the verb and resource. The HTTP path is provided, and it distinguishes from sibling tools like pc_post_issues_by_id_work_products (which creates). However, it lacks detail on what 'work products' are.
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. The description only states the operation, leaving the agent to infer from context. Sibling tools that create, update, or delete work products exist, but no distinction is made.
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 'Authorization class: board', which hints at permission requirements but does not contradict annotations. No additional behavioral details (e.g., what 'resolve' entails) are provided, but the annotations carry the burden.
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, but the first sentence merely repeats the title. The second adds minimal useful context. While it avoids fluff, it sacrifices completeness 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?
The description is too sparse for a tool with nested parameters and no schema descriptions. It fails to explain what 'resolving' a workspace file means, how it differs from listing or getting content, or what the output represents. Even with an output schema present, the agent lacks context for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the input schema provides no documentation for parameters. The description does not explain any parameters (issueId, path, workspace, etc.), leaving the agent to guess their meaning. This is a significant gap.
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 states a verb ('Resolve') and a resource ('issue workspace file'), indicating the general action. However, 'resolve' is ambiguous without further context (e.g., resolve a path, resolve a conflict, resolve a reference). The description does not distinguish this tool from the sibling tools for listing or getting content of file resources.
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 only repeats the title and adds the HTTP method and authorization class. No explicit when-to-use or when-not-to-use instructions are 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no behavioral context beyond the API path and authorization class. It does not mention pagination, rate limits, or response format.
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 short and front-loaded, but it is overly minimal. It could include parameter explanations without significant bloat.
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 details about parameter semantics and behavioral traits. It is incomplete for a tool with required path parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not explain the path parameters (pluginId, jobId). The agent gets no help understanding what each parameter represents.
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 'List runs for a plugin job' clearly states the action and resource. It is specific enough to distinguish from many siblings, though it does not explicitly differentiate from similar tools like pc_get_routines_by_id_runs.
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. It only states the basic purpose.
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, idempotentHint=true. Description adds HTTP method and authorization class but no additional behavioral details like error conditions or rate limits. With annotations, the bar is lower, but description adds minimal 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is very short (3 lines) and concise, but missing critical details like parameter information and usage context. Appropriate length but lacks substance.
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 1 parameter and an output schema, the description is incomplete. It does not explain what a catalog team file is, when to use this tool, or how parameters are used. Requires the agent to infer from name and endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not mention the 'catalogId' parameter. The parameter name is self-explanatory, but description fails to provide any additional meaning or context about how to obtain or use the catalogId.
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?
Description states action 'Get catalog team file' and provides HTTP endpoint, but does not clarify what a 'catalog team file' is or differentiate from sibling file-retrieval tools. It is not a tautology but lacks specificity.
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 on when to use this tool vs alternatives (e.g., pc_get_skills_catalog_by_catalog_id_files). Only includes an authorization class hint, which is insufficient for 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?
Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the HTTP method and authorization class, which do not constitute new behavioral context beyond what annotations infer. No discussion of return format, pagination, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two lines) and to the point, with no filler words. However, it sacrifices informativeness for brevity. Some additional context could be added 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 the tool lists installs for a connection, the description lacks context about what an 'install' represents, the output format (though output schema exists), and when this tool is appropriate. The minimal information leaves the agent guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero descriptions for parameters (0% coverage). The description does not explain what 'connectionId' represents (e.g., the ID of a tool connection). The agent cannot infer the parameter's meaning beyond its name.
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 title 'List tool connection installs' and description clearly indicate this tool lists installs for a given tool connection. The verb 'List' is specific to retrieval, and the sibling tool pc_put_tool_connections_by_connection_id_installs implies a mutate operation, so the purpose is distinct. However, the description does not explicitly differentiate from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. The description mentions authorization class 'board_or_agent' but does not state prerequisites, typical use cases, or when to avoid this tool.
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 non-readonly (readOnlyHint false) and non-destructive (destructiveHint false). The description adds the operation type (PATCH) and authorization class but does not disclose behavioral traits such as constraints on budgetMonthlyCents, side effects, response format, or rate limits.
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 short (3 sentences) with a clear first sentence. However, it includes technical details (endpoint, auth class) that are arguably redundant with the input schema and annotations. It could be more informative without becoming verbose.
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 2 parameters, nested objects, and an output schema, the description is incomplete. It does not explain the parameters, response structure, or how this tool relates to other budget tools (e.g., pc_patch_companies_by_company_id_budgets).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no parameter explanations. It does not clarify that agentId identifies the agent or that budgetMonthlyCents is in cents. The description adds no value beyond the schema structure.
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 'Update agent budget', clearly identifying the action and resource. The API endpoint and authorization class provide additional context. However, it does not explicitly differentiate from sibling tools like pc_patch_companies_by_company_id_budgets, though the per-agent scope is implied by the path.
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 on when to use this tool versus alternatives (e.g., company-level budget tools). Does not mention prerequisites, contexts where it should or should not be used, or 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?
Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, but the description provides no additional behavioral context. It mentions 'Authorization class: board' but does not explain whether permissions are replaced or merged, or what side effects occur. Contradiction with annotations is absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (3 lines) but under-informative. It front-loads the purpose but wastes space on the technical endpoint specification. It lacks necessary details, so conciseness here is a negative trait.
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, the description omits critical context for a mutation tool: effects on existing permissions, whether the operation is additive or replacing, required permissions, and error conditions. The description is insufficient for an agent to invoke safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds no meaning to parameters. The schema defines path and body with grants, but the description does not explain what grants represent or how to use the permissionKey enum or scope. The agent gains no extra insight beyond the raw 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 title and description clearly state the tool updates explicit company member permissions. The verb 'Update' and resource 'explicit company member permissions' are specific. However, it does not distinguish from sibling tools like the other patch member tool that may update member properties rather than 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?
No guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., member must exist), when to use instead of the other patch member tool, or when modifications are not appropriate. The description only states the endpoint.
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 the HTTP method (PATCH) and authorization class, but does not disclose what 'update' entails (e.g., whether it replaces or merges content, effects on existing data). Annotations already indicate non-idempotent and non-destructive, but the description lacks behavioral detail beyond that.
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, but it sacrifices essential details. It is concise but lacks necessary parameter and usage information.
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 nested parameters and existence of an output schema, the description is insufficient. It does not explain what the file content should be or how the update operates, leaving significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description provides no explanation of the 'path' or 'body' parameters or their fields (e.g., 'content'). The agent receives no guidance on how to structure the input.
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 the tool updates a skill file and provides the HTTP method and endpoint path. The verb 'Update' is clear, but it does not differentiate from sibling tools like delete or get files. The resource is clearly identified.
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 on when to use this tool versus alternatives (e.g., get, delete, or other file operations). The description mentions authorization class, but does not specify prerequisites or context for usage.
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 this is a write operation (readOnlyHint=false) and not destructive. The description adds 'PATCH' and 'Authorization class: board', but doesn't disclose important behavioral traits like idempotency, side effects, or what changes are applied (e.g., partial update semantics). openWorldHint=true is not addressed. The description adds marginal value over annotations.
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 concise (two short sentences). However, it repeats the title and adds only technical boilerplate. A better structure would include a brief explanation of parameters and usage context. It earns no waste penalty but also no bonus for effective organization.
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 complexity (nested body parameters, 0% schema coverage) and the presence of sibling tools, the description is incomplete. It lacks parameter descriptions, usage context, return value information, and any behavioral details. The output schema exists but is not referenced. The agent has insufficient information to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions exist in the input schema. The tool description does not explain any parameters (e.g., what fields like 'name', 'status', 'description' do, or the meaning of path parameters 'companyId' and 'definitionId'). This is a severe gap for a tool with 2 parameters and nested objects, leaving the agent unable to understand what to provide.
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 'Update a user secret definition', indicating the action (update) and resource (user secret definition). However, it does not differentiate this tool from its siblings like create (POST) or delete (DELETE) tools, which are also available. The technical details (PATCH, auth class) add some context but don't clarify purpose relative to alternatives.
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 on when to use this tool versus alternatives (e.g., when to create vs. update vs. delete). There is no mention of prerequisites (e.g., the definition must exist) or when not to use it. The description is minimal and doesn't help the agent decide if this is the correct tool.
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 readOnlyHint=false (modifying) and destructiveHint=false. The description adds only the HTTP method (PATCH) and authorization class, which are minimal. It does not disclose behavioral traits like immediate effect, partial update nature, or whether changes persist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences), but it omits essential parameter details and usage context. It is concise at the expense of completeness, making it less helpful for an AI agent.
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 complexity (24 boolean fields in a nested object) and the presence of an output schema, the description lacks completeness. It does not explain the purpose of each setting, the effect of updates, or the request/response format. It barely qualifies as minimally viable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it provides no information about the 'body' parameter or its many properties. The agent must rely solely on the schema, which lists boolean names without explanations. This is a critical gap.
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 'Update experimental instance settings' with a specific verb and resource, distinguishing it from sibling tools like pc_get_instance_settings_experimental (read) and pc_patch_instance_settings (update non-experimental). However, it could explicitly contrast with these siblings.
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 on when to use this tool instead of alternatives. It does not mention prerequisites, when not to use it, or that reading experimental settings should use pc_get_instance_settings_experimental. The description lacks any usage 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 readOnlyHint=false and openWorldHint=true, setting expectations for a non-read, potentially side-effectful operation. The description adds that the operation uses PATCH and requires 'board_or_agent' authorization, which provides some behavioral context. However, it does not disclose what specific changes are irreversible, what side effects occur, or what the output schema contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) but omits critical information. The first line repeats the title, and the second line is a technical detail that, while useful, does not compensate for the lack of parameter guidance or usage context. It is too brief to be effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity—two required parameters with deeply nested objects in the body—the description is severely incomplete. There is no explanation of return values despite an output schema existing. The agent lacks sufficient information to correctly invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, meaning no parameter descriptions exist. The tool description does not add any meaning to the parameters—it does not explain the 'path' or 'body' parameters, nor does it describe the many nested fields in the body. An agent cannot understand what to pass without additional documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a project', which is a specific verb-resource pair. However, it does not distinguish this tool from sibling update tools like pc_patch_issues_by_id or pc_patch_goals_by_id, nor does it explain how it differs from other project-related tools such as pc_post_companies_by_company_id_projects (create) or pc_delete_projects_by_id.
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 prerequisites, and no indication of when not to use it. The description only provides a technical line about the HTTP method and authorization class, which does not help the agent decide contextually.
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 write operation, not destructive, not idempotent. Description adds little beyond the HTTP method and auth class. Missing details like partial update behavior, side effects, or response structure.
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 short but repeats the title. It could be more concise by removing redundancy and adding value. However, it is not overly verbose.
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 complex nested parameters, no schema descriptions, and an output schema present but not described, the description is deficient. It does not cover what the tool does beyond the bare minimum.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides zero information about parameters. It does not explain any field meanings, constraints, or usage.
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 'Update a routine trigger' which clearly indicates the verb and resource. However, it does not differentiate from sibling tools like pc_post_routines_by_id_triggers (create) or pc_delete_routine_triggers_by_id (delete).
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 context. It only mentions authorization class and HTTP method.
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 adds 'Authorization class: board', which is an auth detail beyond annotations. Annotations already indicate readOnlyHint=false and destructiveHint=false. The description does not disclose side effects, idempotency, or what happens during the update (e.g., partial updates, validation, or if missing fields are reset).
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 short but repeats the title verbatim. The second sentence adds operational trivia (Paperclip operation, auth class) that is not essential for agent usage. It is not wasteful but could be more focused on tool semantics.
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 is a mutation with nested parameters and no parameter documentation, the description is insufficient. The presence of an output schema does not compensate for the lack of information about the input fields, update semantics, or when this tool is appropriate. An agent would need to guess or rely on the schema alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no information about the two required parameters (path with id, body with config, status, isDefault, displayName). It does not explain what each field does, constraints, or relationships. The description is entirely silent on 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 title and description clearly state 'Update a secret provider configuration', specifying the verb 'Update' and the resource 'secret provider configuration'. The description also includes the HTTP method and path, which clarifies the operation. However, it does not explicitly distinguish this tool from sibling tools like get, delete, or other patch tools on different resources, but the resource type is uniquely identified.
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 pc_get_secret_provider_configs_by_id, pc_delete_secret_provider_configs_by_id, or pc_post_secret_provider_configs_by_id_default. There is no mention of prerequisites, context, or comparison to other 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?
Annotations already indicate the tool is not read-only and not destructive. The description adds the HTTP method (PATCH) and authorization class ('board'), but does not clarify whether the update is partial or full, nor any side effects like cascading status changes. Behavioral traits are minimally disclosed.
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 concise (two lines) and front-loads the purpose. However, it omits essential details, making it too sparse. It earns its place but lacks depth.
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 (many optional body fields, nested objects) and the existence of an output schema, the description is incomplete. It does not explain the response, partial update behavior, or constraints (e.g., can 'type' be changed after creation?). The description could be more helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameter. The agent must deduce from names like 'applicationId' and 'body' properties. This is insufficient for correct parameter usage, especially for fields like 'pluginId' or 'ownerUserId' that have nullable types.
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 tool application, which distinguishes it from creation (pc_post_companies_by_company_id_tools_applications) and deletion (pc_delete_tool_applications_by_application_id) siblings. However, it does not explicitly differentiate from other update tools, but the name and title are sufficient.
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 prerequisites, or contexts where updating is appropriate instead of recreating or deleting. The user must infer from the schema and general knowledge.
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 provide readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds only 'Authorization class: board', which is minor. No additional context on side effects, required permissions, or outcome of update 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 brief (two sentences) and front-loaded with the purpose. However, it is under-informative; the second sentence provides internal operational detail (API path and auth class) that is not helpful for selection or invocation.
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 complex input schema and multiple sibling tools, the description is too sparse. It does not explain the effect of the update, return values (output schema exists but description doesn't mention it), or how to construct the body. The annotations and schema alone are insufficient without descriptive context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%; the description does not mention any parameters despite a complex input schema with many fields (body with properties like name, config, status, etc., and path with connectionId). Without any parameter descriptions, the agent cannot understand required inputs.
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 'Update a tool connection', which is a specific verb+resource combination. It distinguishes from sibling tools like 'get' and 'delete' by indicating modification. However, it could be more explicit about modifying an existing connection.
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 on when to use this tool versus alternatives (e.g., create, delete). The description does not provide context for appropriate usage scenarios.
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 readOnlyHint=false (mutation) and destructiveHint=false (non-destructive). The description adds the authorization class 'board_or_agent', which is helpful for understanding required permissions. However, it does not disclose other behavioral traits like rate limits, idempotency implications, or the key's visibility after creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (two sentences), the first of which simply repeats the title. It lacks substance and does not make efficient use of space to convey critical information. The structure is minimal but not effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (two required parameters, including a nested oneOf scope), the description is grossly insufficient. It does not explain what the 'id' in path refers to, what the 'name' field represents, or how to choose and populate the scope. The presence of an output schema does not compensate for missing usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain any of the parameters (id in path, name and scope in body). The complex scope oneOf with three kinds (standard, task_bridge, skill_test) is entirely undocumented textually, leaving the agent without guidance on how to properly structure the input.
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 title and description clearly state the purpose is to create an API key for an agent. The HTTP path confirms the resource. However, it does not explicitly differentiate from sibling tools like pc_get_agents_by_id_keys (list) or pc_delete_agents_by_id_keys_by_key_id (delete), though the verb 'create' implies creation.
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, such as when to create a key vs. list or delete keys. There is no mention of prerequisites (e.g., the agent must exist) or any context about usage scenarios.
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 it's not read-only and open-world, but the description fails to explain side effects (e.g., starting an OAuth flow, requiring user interaction). 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief (two sentences) but wastes the first on repeating the title. The second sentence adds the API path and auth class, which is somewhat useful but not essential.
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 a required output schema but no description of its content, and parameters are unexplained, the description is insufficient for an agent to understand the full context of usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameter (subjectUserId, scopes, returnTo, connectionId). The description adds no 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 it starts user authorization for a tool connection, which aligns with the title. However, it does not differentiate from the sibling tool 'pc_post_agents_me_connections_by_connection_id_token', which likely handles the next step.
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 on when to use this tool vs alternatives. The mention of 'Authorization class: board' is vague and does not help an agent decide 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 description adds 'Paperclip operation: POST /api/cli-auth/challenges/{id}/cancel. Authorization class: public.' This provides the HTTP method and auth requirement, which is useful. However, annotations already set destructiveHint=true, so the destructive nature is known. The description does not explain side effects (e.g., what happens to the challenge, whether it can be undone) or other behavioral traits beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at two sentences, which is positive for brevity. However, it sacrifices necessary detail for conciseness, especially regarding parameters. The structure is straightforward but could be improved by front-loading the most critical information about cancellation behavior.
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 complexity of the CLI auth challenge lifecycle (with siblings for create, approve, revoke), the description is incomplete. It does not explain what happens upon cancellation, what the output schema contains, or error conditions. The presence of an output schema and annotations somewhat compensates, but the description alone leaves significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has two parameters (path.id and body.token) with no descriptions in the schema (0% coverage). The tool description fails to explain what these parameters represent or how they should be used. For example, it does not clarify that 'id' identifies the challenge or that 'token' is the authentication token. This leaves the agent guessing about parameter meaning.
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 'Cancel a CLI auth challenge' which clearly identifies the action and resource. The tool name and title align with this purpose. However, it does not explicitly distinguish from siblings like 'approve' or 'revoke', but the verb 'cancel' is distinct enough. A more detailed explanation of what a CLI auth challenge is would improve 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 such as pc_post_cli_auth_challenges_by_id_approve or pc_post_cli_auth_revoke_current. No context, prerequisites, or exclusions are mentioned. The agent must 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 already indicate readOnlyHint=false (write), destructiveHint=false, idempotentHint=false. The description adds only the authorization class, which is not behavioral. It does not disclose side effects, the nature of the operation (e.g., finalizing OAuth flow), or any potential outcomes beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two lines) but includes irrelevant technical details ('Paperclip operation: ...') that waste space. It is concise but not optimally structured for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a multi-step connection flow with OAuth parameters and an output schema, the description is severely lacking. It does not explain the overall process, parameter roles, output, or prerequisites, leaving the agent with insufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain parameters. It provides no description for 'pendingConnectionId', 'code', or 'state'. The agent receives no hints about what these mean (e.g., OAuth code and state), making it impossible to use correctly without external knowledge.
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 title and first line clearly state 'Finish a cloud upstream connection', which is a specific verb-resource pair. However, it does not differentiate this tool from sibling tools like pc_post_cloud_upstreams_connect_start, and the additional technical details (Paperclip operation, authorization class) do not aid purpose 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?
No guidance on when to use this tool versus alternatives. The description does not mention that this is the second step after starting a connection, nor does it indicate 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 already indicate readOnlyHint=false, destructiveHint=false. The description adds the HTTP method and auth class but does not disclose side effects, idempotency, or other behaviors beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) but lacks substance. It front-loads the purpose but provides no parameter or usage detail, making it efficient but insufficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 2 parameters, 0% schema coverage, nested objects, and no parameter descriptions, the description fails to provide meaningful context. It does not explain what an activity entry is, how to fill parameters, or what the output schema contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description gives no information about parameters. Required fields like actorId, action, entityType, entityId, and companyId are left completely unexplained.
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?
Title and description clearly state 'Create an activity entry,' and the tool name includes 'post' indicating creation. However, it does not distinguish from sibling tools like `pc_get_companies_by_company_id_activity` which reads activity.
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 on when to use this tool vs alternatives. The description only provides the HTTP path and authorization class, not usage context 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?
The description adds minimal behavioral context beyond the annotations. It does not describe side effects, what the export triggers (e.g., background job), or auth requirements beyond what is already in the text.
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 but lacks crucial information about parameters and usage. It is not well-structured for a tool with a complex input 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?
Given the tool's complexity (many nested parameters, output schema present but not described), the description is severely incomplete. It does not cover what the export includes, how to configure it, or what the response looks like.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain any of the input schema parameters, which have zero documentation. With schema coverage at 0%, the description should compensate but does not, leaving the agent to guess from property names only.
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 'Export a company' and identifies the tool as a legacy legacy singular form, distinguishing it from the plural version. However, it does not explain what the export produces or the 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?
The description implies it is legacy via the title, but provides no explicit guidance on when to use this tool vs the plural form (pc_post_companies_by_company_id_exports) or any other alternative. No exclusions or context are 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 already indicate it is not read-only, not idempotent, and not destructive. The description adds the authorization class and HTTP method, but does not disclose any other behavioral traits such as side effects or rate limits.
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 but lacks necessary detail. It could be more informative without being verbose, but it is not overly long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the input schema (2 parameters with many nested objects), the description is severely incomplete. It does not explain what a finance event is, what the required fields are, or what the response looks like. An output schema exists but is not referenced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of the parameters. The body contains many fields (e.g., eventKind, amountCents, biller) that are not described, leaving the agent without guidance on how to populate them.
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 title and description clearly state the action ('Record a finance event') and provide the HTTP method and path. The purpose is specific, but it does not differentiate from sibling tools like the GET finance events or POST cost events.
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 includes the authorization class ('board_or_agent'), which gives some context on who can use it, but does not explain when to use this tool versus alternatives like the GET finance events or other POST cost 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?
Beyond the annotations (readOnlyHint false, destructiveHint false, idempotentHint false), the description adds minimal behavioral context. It mentions authorization but does not disclose side effects, idempotency, or limitations such as whether applying an import overwrites data or requires certain permissions beyond 'board_or_agent'.
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 title. However, it sacrifices substance for brevity. While not verbose, it does not use its structure to convey necessary information effectively.
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 presence of an output schema, the description need not detail return values, but it fails to explain the tool's role in the import workflow (e.g., that it likely finalizes a previously previewed import). It lacks context on prerequisites, sequence, or relationships with sibling import tools.
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 two parameters (body and path.companyId) with 50% description coverage, but the tool description adds no information about their meaning, format, or how they affect the operation. The agent must rely solely on the schema, which is insufficient.
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 states 'Apply company import' and provides the HTTP method and path, which gives a basic idea of the action. However, it does not explain what 'apply' means in context or distinguish it from sibling tools like pc_post_companies_import or pc_post_companies_by_company_id_imports_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 usage guidance is provided. The description does not indicate when this tool should be used, what preconditions exist (e.g., a prior import preview), or when alternatives 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 indicate readOnlyHint=false, destructiveHint=false, openWorldHint=true. The description adds no behavioral context beyond repeating the HTTP method and auth class. It does not clarify side effects, return value, or any non-obvious 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) and to the point. While concise, it omits useful structure like a summary of key parameters or use cases. It is decent but not optimally formatted for quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (many nested parameters, required fields), the description is grossly incomplete. It fails to mention the mandatory 'title' and 'status' fields, and offers no overview of the issue creation process or returned data. Output schema exists but description ignores it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. However, it provides no explanation of any parameter (e.g., body.title, status, etc.). The schema itself is self-documenting but the omission of parameter guidance is a significant gap.
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 'Create an issue' clearly states the verb and resource. However, it does not distinguish this tool from sibling tools like pc_post_issues_by_id_children (create child issue) or pc_post_issues_by_id_interactions. The company-specific scope is implied by the path but not emphasized.
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 an authorization class (board_or_agent) but offers no guidance on when to use this tool versus alternatives. It does not mention prerequisites, related tools, or context for selecting this operation.
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 provides the endpoint and authorization class, but does not explain behavioral traits such as whether the old secret is immediately invalidated, if the operation requires confirmation, or any side effects. Annotations indicate it is not read-only, not idempotent, and not destructive, but the description adds little beyond that.
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 it lacks essential details. It is concise but wasteful because it does not provide value beyond the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple parameters, output schema exists), the description is severely incomplete. It does not explain return values, constraints, or the meaning of the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameters (value, externalRef, providerConfigId, providerVersionRef, companyId, secretId). The AI cannot understand what inputs are expected or how to use them.
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 title and description clearly state the tool rotates a user secret value. However, it does not distinguish from similar sibling tools like pc_post_secrets_by_id_rotate (which rotates company-level secrets).
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 on when to use this tool versus alternatives (e.g., rotation of company secrets). No prerequisites or context provided.
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?
Annotats indicate it's not read-only, not destructive, and not idempotent. The description adds no behavioral context beyond the HTTP method and authorization. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very short (2 sentences) but the first sentence repeats the title wastefully. It is concise but lacks substance.
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, the description fails to explain what the bundle is, what the body parameter does, or how to use it. Incomplete for a creation tool with two required parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain the parameters (companyId, agentMessage) at all, leaving the agent to rely solely on the schema structure.
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 ('Create') and resource ('OpenClaw invite prompt bundle'). The purpose is specific and distinguishes this tool from sibling company-related tools, though the term 'OpenClaw' is unexplained.
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 on when to use this tool versus alternatives, such as generic invite tools. Only technical details (HTTP path and auth class) are 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?
Description mentions 'Authorization class: board', which is a behavioral detail beyond annotations. However, it does not disclose idempotency, side effects, or what happens if a duplicate config is created. Annotations already indicate non-read-only, non-destructive, and non-idempotent, so the description adds marginal value.
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 brief (three sentences) but lacks structure. The first sentence repeats the title, while the second and third provide endpoint and auth info. It is concise but not optimally organized to convey purpose and usage efficiently.
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 (so return values are not needed in the description), the description is very minimal. For a creation tool with many siblings, it lacks context about what a secret provider configuration is, when to create one, or any constraints (e.g., maximum number of configs).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of parameters such as provider, config, displayName, or companyId. The tool has nested objects with multiple fields, but the description is silent, forcing the agent to rely solely on the schema.
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 title and description both state 'Create a secret provider configuration', which is clear but tautological. The description adds the endpoint and authorization class, which helps confirm the action but does not differentiate from siblings beyond the specific resource.
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 on when to use this tool versus alternatives like pc_get_secret_provider_configs or pc_patch_secret_provider_configs. There are many sibling tools for secret providers, but the description lacks context on prerequisites or typical scenarios.
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 no behavioral context beyond what annotations already provide (destructiveHint=true). It fails to explain what gets reset (e.g., configuration, status) or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and concise, but it lacks structured detail. It conveys the operation and authorization class efficiently but omits important information that could be included without verbosity.
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 open-world body schema and the presence of an output schema, the description is incomplete. It does not explain the required body contents or the result of resetting, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the path parameters (companyId, skillId) or the body object. This is critical for correct invocation, and no compensating information is given.
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 verb 'Reset' and the resource 'a company skill', distinguishing it from sibling tools like get, patch, and delete. However, it lacks specificity on what 'reset' entails.
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. Sibling tools include patch, delete, and other reset operations, but no context for selection is provided.
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 that the tool is a write operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description does not add any behavioral context beyond what annotations provide. It mentions authorization class but that's not behavioral.
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 concise and to the point with two sentences. However, it sacrifices informative value for brevity. It could be more structured to include parameter details or usage notes.
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 nested objects and an output schema, the description is incomplete. It does not explain what a version is, what the request body should contain, or what the response looks like. The agent cannot fully understand the tool's requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It does not. The body parameter is an object with additionalProperties: {}, which is very open-ended. No hint about what fields the body should contain (e.g., version details, content). This is a significant gap for an AI 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 title 'Create a skill version' and name clearly indicate the tool's purpose. The description restates this and adds the HTTP method and path, which reinforces the purpose. However, it does not distinguish from sibling tools like pc_get_companies_by_company_id_skills_by_skill_id_versions, which is a GET operation. The purpose is specific but lacks 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?
The description provides no guidance on when to use this tool versus alternatives. No mention of prerequisites, conditions, or when not to use it. The agent is left without context for 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 indicate a write operation (readOnlyHint=false) with non-destructive and non-idempotent behavior. The description adds that authorization is 'board_or_agent', which is useful. However, it does not explain side effects, idempotency details, or what happens during an import (e.g., overwrite, merge). The additional auth info raises the score slightly but still lacks depth.
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 short and front-loaded with the title, but it wastes the first line by repeating the tool's already-known title. The second and third lines provide basic info (HTTP method and auth class) but could be more efficiently combined or expanded. It is not overly verbose, but it could be more structured.
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 (nested objects, required params, output schema), the description is insufficient. It omits details about the meaning of 'source', expected output, success conditions, and error scenarios. The agent would need to infer too much from the schema alone, which is not described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters are described in the description; schema coverage is 0%. The 'source' field in the body is not explained, and the 'companyId' path parameter is only implied. The description does not compensate for the lack of schema documentation, leaving the agent to guess parameter meaning.
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 states 'Import a skill' and provides the HTTP method and path, which conveys the basic action. However, it does not distinguish this tool from sibling tools like 'pc_post_companies_by_company_id_skills' (likely create skill) or other import/export operations. The purpose is clear but vague, lacking specificity about what 'import' entails.
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. There is no mention of prerequisites, such as whether a source file or catalog entry is needed, nor any indication of when not to use it. The description offers no context for 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 description adds no behavioral insights beyond the title. Annotations already indicate it is a mutation (readOnlyHint false), but the description does not disclose side effects, permissions, rate limits, or response structure. The inclusion of an internal operation path and authorization class is not useful for an AI agent.
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) but lacks structure. It omits usage examples, parameter explanations, or output details. While concise, it sacrifices informativeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the input schema (nested objects, multiple required fields, enums, patterns) and the presence of an output schema, the description is severely incomplete. It fails to explain what a tool application is, how to construct the request, or what the response contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0% description coverage, and the description provides no explanation of any parameter (path.companyId, body.name, type, status, etc.). The agent has no guidance on how to populate these fields, making it nearly impossible to use correctly.
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 'Create a tool application', which clearly identifies the action and resource. However, it does not elaborate on what a tool application is or distinguish it from similar sibling tools like 'Create a tool connection'.
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. It lacks context about prerequisites, typical use cases, or exclusions. Sibling tools include many creation endpoints with no differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations indicating openWorldHint=true (side effects possible), the description adds no behavioral context beyond being a POST operation. It does not explain what 'finish' entails or what state changes occur.
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), but the second sentence about API operation and auth class is not actionable for an AI agent. It is concise but misses key semantic content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has nested objects, no parameter descriptions, and an output schema (unseen), the description is far too minimal to guide correct invocation. It lacks context on what the tool does beyond the title.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no parameter descriptions), and the description does not explain any parameters. The agent receives no help understanding what 'access', 'enabledCatalogEntryIds', or 'askFirstCatalogEntryIds' mean.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action 'Finish a gallery app connection and profile setup' with a specific resource, but it does not differentiate this tool from its many siblings (e.g., other tools related to gallery apps or connections).
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 on when to use this tool versus alternatives like connect, reconnect, or health check for gallery apps. The description lacks context for usage.
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 readOnlyHint=false (write operation) and destructiveHint=false. The description adds no behavioral context beyond 'Create' and the authorization class. It does not disclose side effects, duplicate behavior, or post-creation state, leaving the agent with minimal transparency.
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 lines) with no wasted words, but it is too minimal for the tool's complexity. While concise, it sacrifices necessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (many nested parameters in body, 0% schema coverage, and output schema present but undocumented in description), the description is severely incomplete. It fails to provide essential context for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema parameter coverage is 0%, yet the description provides no explanation of any parameters, including the complex body object with many nested fields. The agent must rely solely on property names and types, which is insufficient for correct invocation.
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 title and description clearly state 'Create a tool connection' with the HTTP method and path. The verb 'Create' and resource 'tool connection' are specific. However, it does not differentiate from sibling tools like get, patch, or delete beyond the implied creation action.
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 on when to use this tool versus alternatives. No prerequisites (e.g., required company ID, permissions) or conditions are mentioned. The description lacks explicit when-to-use or when-not-to-use 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?
Annotations indicate readOnlyHint=false (mutation) and openWorldHint=true, but the description adds no behavioral context beyond the HTTP method and authorization class. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) but overly brief. It repeats the title and provides the HTTP path, but lacks structural organization for quick scanning.
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 is a mutation with two parameters and an output schema (not described), the description is incomplete. It omits return value details, prerequisites, and any context about the installation process.
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 only 50%; the body parameter has a vague description ('Optional JSON compatibility payload...'), and path properties have no description. The description fails to add meaningful parameter semantics.
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 states 'Install a safe tool example' which identifies the verb and resource, but does not elaborate on what installation means (e.g., adding to a company's tool examples list). It distinguishes from sibling 'smoke' but lacks specificity.
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 there any prerequisites, side effects, or exclusions mentioned. The agent is left to infer 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?
Annotations already indicate non-readOnly, non-idempotent, non-destructive, and open-world. The description adds the authorization class 'board', which is extra context but does not explain the behavioral impact of reordering (e.g., whether it changes other policies or triggers side effects). The additional value beyond annotations 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short but not concise in a helpful way. It is essentially a tautology of the title plus endpoint info. There is no structured breakdown; it lacks necessary details while not being efficient.
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, the description fails to explain what reordering does (e.g., the array of policy IDs defines the new order). For a tool that modifies the sequence of policies, this is a critical gap. The description is not complete enough given the operation's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the input schema provides no parameter descriptions. The description also adds no parameter semantics beyond the schema's field names and types. For example, it does not explain that 'policyIds' indicates the new ordering or that the order in the array is significant.
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 title and first line of description clearly state 'Reorder tool policies', which is a specific verb+resource. However, no distinction is made from sibling tools like pc_get_companies_by_company_id_tools_policies or pc_post_companies_by_company_id_tools_policies, so it's not fully differentiated.
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 merely restates the operation and gives the endpoint, lacking any context about prerequisites or when reordering 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?
Annotations already indicate destructiveHint=true. The description adds only the HTTP method and URL, but does not explain the implications of disabling (e.g., whether it is reversible, effects on running sessions). Minimal behavioral context beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but includes unnecessary technical details (the full HTTP path and authorization class) that may not be useful for an AI agent. It could be more concise and focus on the tool's purpose.
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 tool is destructive with required parameters, yet the description does not explain the consequences of disabling, such as whether it can be undone or requires a reason. The output schema exists but is not referenced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not describe any parameters. The body includes a 'reason' field, but its purpose or constraints are not explained. This forces the agent to rely solely on 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 it disables an approved stdio MCP template. The verb 'disable' and resource 'approved stdio MCP template' are specific. However, it does not differentiate from potential sibling actions like deleting or enabling templates.
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., deleting a template or enabling/disabling other tools). The description lacks context on prerequisites or scenarios.
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 the authorization class 'board' beyond annotations, but does not disclose side effects, error conditions, or return value behavior. Annotations already indicate non-readonly, non-destructive, non-idempotent, but the description adds minimal 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two lines), which is concise but at the expense of meaningful content. It lacks essential details but is not overly verbose.
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, the description does not hint at what the response contains. Nested parameters are undocumented. For a creation tool with complex schema, this is insufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate but provides no information about parameters (body, path) or their nested fields, constraints, or enums. The agent gets no guidance on what to populate.
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 'Create a user secret definition' and includes the HTTP method and endpoint, providing a specific action and resource. However, it does not differentiate from other 'create' tools or explain what a user secret definition is.
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 on when to use this tool versus other secret-related tools (e.g., pc_post_companies_by_company_id_secrets) or when not to use it. No context on prerequisites 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?
The description mentions the authorization class and the HTTP method, but annotations already convey safety cues (readOnlyHint=false, etc.). It does not explain the nature of 'preview' (e.g., whether it is a dry run or has side effects). Minimal added value beyond structured fields.
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), but it lacks informative content. It is efficiently sized but does not earn its place with meaningful guidance.
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 (nested parameters, output schema available) and the lack of parameter descriptions, the description is severely incomplete. It does not explain what the preview returns or how to use the response, which is critical for a preview operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, with a complex nested 'body' parameter. The description offers zero parameter information, failing to compensate for the schema's lack of documentation. This is a severe gap.
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 'Preview a company import', using a specific verb and resource. The addition of '(legacy route)' hints at differentiation from newer import endpoints, but does not explicitly distinguish from siblings like pc_post_companies_import.
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 fails to mention prerequisites, context, or scenarios where this legacy route is appropriate over other import preview 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?
Annotations indicate it is not read-only, not destructive, and not idempotent. The description adds only an authorization class ('board_or_agent'), which provides minimal behavioral context. No disclosure of side effects, what the probe does, or any important behaviors.
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) and avoids fluff, but it is under-specified. Conciseness is achieved at the cost of completeness.
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 an output schema existing (not shown), the description provides no information about the probe's purpose, return value, or behavior. With two parameters and many sibling tools, the description is insufficient for an agent to understand the tool's 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 coverage is 50%, and the description adds no meaning to parameters. The 'body' parameter description is vague ('optional JSON compatibility payload'), and 'path' has no description. The description does not explain parameter usage or constraints.
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 states the tool 'Probe an environment', which is a verb+resource. However, 'probe' is vague and does not specify what kind of probe (health check, data retrieval, etc.). It does not differentiate from sibling environment tools like GET or PATCH.
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 context about prerequisites, intended scenarios, 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 show readOnlyHint=false and destructiveHint=false, but the description adds little transparency. It mentions the HTTP method and authorization class, but does not explain side effects, state changes, or what the command execution entails.
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 extremely concise (one sentence plus metadata), which is efficient but omits crucial information. It is front-loaded with the core purpose, but lacks structure and completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the input schema (nested objects, optional fields) and the presence of sibling runtime tools, the description fails to provide essential context about what runtime commands are, common actions, expected outcomes, or when to use this tool. It is incomplete for effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the parameters (body with serviceIndex, runtimeServiceId, workspaceCommandId; path with id and action). The agent receives no additional meaning beyond the parameter names.
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 runs a runtime command in a workspace, providing a specific verb and resource. It distinguishes from sibling tools like pc_post_execution_workspaces_by_id_runtime_services_by_action by using 'command' versus 'services', though it lacks further differentiation or examples of commands.
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 over alternatives. There is no mention of context, prerequisites, or when not to use it, 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 indicate this is not read-only, not idempotent, and not destructive, but the description adds minimal behavioral context beyond stating the endpoint and authorization class. It does not explain what checking out does to the issue (e.g., locking, preventing edits) or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short with two sentences, but the second sentence is technical (endpoint and auth class) and does not add value for the agent. It is concise but lacks informative structure.
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 2 required parameters, nested objects, and an output schema, the description is inadequate. It does not explain the purpose of the output, the meaning of expectedStatuses, or the effect of the operation, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain any of the parameters, such as agentId (which agent is checking out) or expectedStatuses (what statuses are required). The agent cannot infer parameter meaning from the description alone.
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 title and description clearly state 'Check out an issue', which is a specific verb-resource combination. However, it does not differentiate this tool from siblings like pc_patch_issues_by_id or pc_post_issues_by_id_release, which could also involve issue state changes.
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 when to check out vs. release an issue. No context on prerequisites or scenarios 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?
The description adds minimal behavioral insight beyond annotations: it mentions the HTTP method (POST) and authorization class. It does not disclose side effects, idempotency, or other traits not already captured by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise but under-specified. It includes useful details (operation, auth) but lacks crucial context for effective tool invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (many siblings, rich schema), the description is severely incomplete. It does not explain interaction concepts, parameter usage, or return values, relying entirely on the schema and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description provides no information about parameters. It does not explain the complex oneOf structure or required fields, leaving the agent to interpret the schema alone.
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 creates an issue thread interaction, which is a distinct action among siblings (accept, reject, respond, etc.). However, it does not elaborate on what constitutes an interaction, leaving some 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 on when to use this tool versus alternative sibling tools (e.g., accept, reject, respond). The description does not specify context 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 already indicate destructiveHint=true, but the description adds no behavioral details beyond that. No mention of side effects, reversibility, or authorization requirements beyond the operation string.
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?
Very concise at two sentences, but the first sentence merely repeats the title. The second provides HTTP details but lacks substance. Could be restructured to front-load key behavioral info.
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 that it is a destructive operation with multiple parameters and an output schema, the description is incomplete. It does not explain return values, when rejection is possible, or error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain any parameter meaning, such as what 'reason' is for or what 'id' and 'interactionId' refer to.
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 title and description clearly indicate the tool rejects an issue thread interaction. It distinguishes from siblings like accept by using 'reject'. However, it does not elaborate on what rejection means in this domain.
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 on when to use this tool vs alternatives like accept, cancel, or respond. No prerequisites or context provided.
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 minimal (readOnlyHint=false, destructiveHint=false) and the description merely repeats the action. It does not disclose side effects, permission requirements beyond 'board_or_agent', or what happens to the low-trust output after promotion. The description fails to add value 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (two sentences), but the first sentence repeats the title without adding value, and the second provides only the HTTP path and auth class. It is not overly long, but the content is minimal and not fully earning 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 is a mutation with 2 parameters and 0% schema coverage, the description should explain the return value (output schema exists but is not described) and the effect of the operation. It lacks completeness; the agent would have to infer behavior from the tool name alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description gives no information about any of the 2 parameters (path and body) or their sub-fields. The agent receives no guidance on what values to provide (e.g., what 'sourceArtifactKind' options mean, or what 'title' and 'summary' represent). This is a critical gap.
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 the tool promotes quarantined low-trust output, providing a specific verb and resource. However, it does not distinguish this tool from other issue-related sibling tools, nor does it elaborate on what 'promote' entails (e.g., changing status, making visible). It is clear but lacks detail for full 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 use this tool versus alternatives. It does not mention prerequisites, when not to use it, or the context of quarantined output. The only hints are the authorization class, but no usage context 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 already indicate readOnlyHint=false and destructiveHint=false, so the mutation nature is clear. The description adds the HTTP method (POST) and authorization class (board_or_agent) but does not disclose idempotency, side effects, or what happens if the action is already resolved.
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 concise with two sentences: one for the action and one for technical details. No redundant information, but it could be better structured to include parameter hints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (required body parameters with enums, optional fields, and an output schema), the description is severely lacking. It does not explain the meaning or usage of any parameters, leaving the agent with insufficient context to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions in the schema. The description does not explain any parameters (outcome, actionId, resolutionNote, sourceIssueStatus) beyond the schema definition. The agent receives no semantic help for constructing valid inputs.
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 title and description clearly state 'Resolve an issue recovery action', which specifies the verb and resource. It is distinct from sibling tools like pc_get_issues_by_id_recovery_actions that list actions. However, it could be more explicit about what 'resolve' entails in terms of outcomes.
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 pc_get_issues_by_id_recovery_actions or other issue mutation tools. No exclusions, prerequisites, or context are mentioned.
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 non-read-only and non-destructive, but the description adds only the operation path and authorization class. It does not clarify whether the preview actually persists changes or what side effects occur.
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 but sacrifices essential details. It could include parameter guidance and output expectations without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the nested input schema and presence of an output schema, the description is grossly incomplete. It fails to describe what the preview returns, how to use the parameters, or how the tool fits into the broader tree control workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain any parameters, including the mode enum (pause, resume, cancel, restore) or the releasePolicy nested object, which are critical for correct usage.
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 the tool previews tree control changes, which is a clear verb-resource pair. It distinguishes from sibling tools by including 'preview' in the name, but the description doesn't explicitly contrast with other tree control 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?
Only authorization class is provided. No guidance on when to use this tool versus alternatives like pc_post_issues_by_id_tree_holds or pc_get_issues_by_id_tree_control_state.
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 readOnlyHint=false and openWorldHint=true. Description adds only the HTTP method and authorization class, which aligns but does not explain side effects, data mutation, or safety considerations 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences), which is efficient but at the cost of omitting crucial information. It is not a model of conciseness because it fails to convey essential details.
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 complexity of the plugin system and many sibling tools, the description is incomplete. It lacks information about return values (despite an output schema), side effects, and appropriate usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameter meanings. The 'key' and 'params' fields in the body are undocumented, leaving the agent to guess their purpose.
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 'Send action via plugin bridge', which specifies a verb and resource, but 'action' is generic and not differentiated from sibling tool 'pc_post_plugins_by_plugin_id_actions_by_key'. The endpoint detail helps slightly, but purpose remains somewhat vague.
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 on when to use this tool versus alternatives like pc_post_plugins_by_plugin_id_actions_by_key. The description lacks context for invocation scenarios 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 indicate readOnlyHint=false (write) and openWorldHint=true (side effects), but the description adds little: it only repeats 'Send data' and provides an obscure 'Authorization class: board'. No disclosure of what happens to the data, rate limits, or consequences.
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 short but includes unnecessary technical details (HTTP method, authorization class) that do not aid an agent. It is brief but lacks substance, making it insufficiently informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 2 required parameters, nested objects, and no parameter descriptions, the description fails to provide essential context for invoking the tool. The existence of an output schema is irrelevant since the description omits input guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not explain any parameters (body.key, body.params, body.companyId). An agent cannot infer what values to provide or their purpose.
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 'Send data via plugin bridge' indicating a clear verb+resource. However, it does not explicitly differentiate from the sibling 'pc_post_plugins_by_plugin_id_bridge_action', which likely performs a different operation (action vs data). The purpose is generally clear but lacks contrast.
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 on when to use this tool versus alternatives like 'pc_post_plugins_by_plugin_id_bridge_action' or other plugin tools. No prerequisites or context for invocation provided.
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 that the tool is not read-only, is not idempotent, and is 'open world' (may have side effects). The description adds no behavioral context beyond these annotations—for example, it does not describe what validation entails, whether it modifies state, or what failures might occur.
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-loads the purpose, which is good for conciseness. However, it is under-specified; additional information about parameters or behavior would improve it without sacrificing 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 the complexity (nested parameters, output schema exists), the description is incomplete. It does not explain what validation checks will be performed, what the output schema contains, or any error conditions. The context is insufficient for an agent to understand the tool's full behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does not explain any parameters—neither the path parameters (pluginId, companyId, folderKey) nor the body parameters (access, requiredFiles, requiredDirectories). The access enum values are self-explanatory, but requiredFiles and requiredDirectories are left ambiguous.
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 validates a plugin local folder, with a specific verb ('validate') and resource identified. However, it does not differentiate this tool from sibling tools that also operate on plugins, such as enabling or disabling plugins.
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 context for when validation is appropriate. The only additional information is the HTTP method and authorization class, which are insufficient for decision-making.
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 mutation (readOnlyHint=false) and dynamic schema (openWorldHint=true). The description adds only HTTP method and auth class, which are minor. It does not explain side effects, error states, or the nature of execution.
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 short but includes a redundant title line. It is concise but lacks substance, sacrificing critical information for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex nested input schema and dynamic parameters, the description is severely incomplete. It does not explain the runContext fields, parameter nature, or output format, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds no information about the 'body' parameter's properties (tool, parameters, runContext). The agent is left to guess their meanings and constraints.
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 'Execute a plugin tool' with a verb and resource. The sibling pc_get_plugins_tools lists tools, so this is the distinct execute action. However, it does not differentiate from other plugin action tools like pc_post_plugins_by_plugin_id_actions_by_key.
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 lacks prerequisites, context, or comparisons to siblings.
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 the endpoint path and authorization class beyond annotations, but does not explain what 'control' does (e.g., start, stop, restart), side effects, or whether the operation is reversible. Given annotations already indicate write but non-destructive, the description contributes minimal behavioral insight.
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 concise at two sentences, but it sacrifices necessary detail. It is minimally structured and does not prioritize key information (e.g., actions available, parameter meanings).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 2 complex parameters (nested objects), 0% parameter coverage, and no output schema explanation, the description is highly incomplete. The agent lacks the information needed to invoke the tool correctly, especially without knowing valid actions or parameter constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of parameters such as 'id', 'workspaceId', 'action', or body fields like 'serviceIndex' and 'runtimeServiceId'. The agent must rely solely on the schema, which lacks descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Control a runtime service in a project workspace', clearly indicating a verb (control) and resource (runtime service) with scope. However, it does not enumerate the possible actions (e.g., start, stop), leaving the agent to infer from the path parameter. While clear, it lacks specificity compared to potential 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 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 similar tools like 'pc_post_execution_workspaces_by_id_runtime_services_by_action'. The description does not mention context, prerequisites, or alternative 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?
Description adds no behavioral context beyond the annotations. Annotations already indicate readOnlyHint=false and destructiveHint=false, but the description does not clarify side effects, idempotency, or what happens when a command runs. The mention of HTTP method and path adds technical detail but not 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short, consisting of two sentences. It is concise but lacks substantive content; the first sentence repeats the title, and the second provides a technical detail. No waste, but insufficient information.
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 complexity of a runtime command execution tool, the description is inadequate. It fails to explain the command's effect, how to specify it via parameters, or what the output represents. With an output schema present, the return type is not mentioned. The description lacks essential context for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters, but it does not mention any parameter names, types, or purpose. The body and path fields remain entirely undocumented, leaving the agent to infer from schema structure alone.
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 title and first sentence clearly state 'Run a runtime command in a project workspace', specifying the verb and resource. However, it does not differentiate from sibling tools like pc_post_projects_by_id_workspaces_by_workspace_id_run_0826c4dc1d, which also involves running something in a workspace.
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 or when not to use this tool. There is no mention of prerequisites, context, or alternative tools. The only extra info is the authorization class, which is a permission hint but not usage guidance.
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 destructive or idempotent hints. The description adds only the URL and auth class, omitting what rotation entails (e.g., invalidates old secret, generates new one), leaving the agent guessing about side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is very short and front-loaded with purpose, then technical details. It is not verbose, but the minimalism sacrifices informativeness. An average score for conciseness that doesn't add much 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?
Given the tool has an output schema and two parameters (one nested), the description is incomplete. It fails to explain the operation's outcome, request body expectations, or any constraints, leaving substantial gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has two parameters (path.id and body) with zero description coverage. The description does not explain what 'id' refers to or what the body requires, leaving the agent without essential semantic context.
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 verb 'Rotate' and resource 'routine trigger secret', and distinguishes from sibling tools like pc_post_secrets_by_id_rotate and pc_patch_routine_triggers_by_id by specifying the endpoint and authorization class. However, it does not explicitly contrast with these alternatives.
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 on when to use this tool versus alternatives (e.g., when to rotate a secret vs. patch a trigger). No prerequisites or context provided.
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, but the description does not explain what 'check' entails (e.g., whether it performs a health probe, returns status, or has side effects). The behavioral impact beyond the HTTP POST method is unclear.
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 short and front-loaded with the purpose, but it omits critical details. While conciseness is valued, it sacrifices completeness 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 the tool has an output schema, the description should reference what the response contains (e.g., health status object). It also lacks context about required preconditions, such as ensuring the secret provider config exists. The description feels 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?
The description adds no information about parameters. With schema coverage at 50%, it should clarify when the optional 'body' is needed or its purpose, but it does not. The schema documentation for 'body' is minimal.
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 states 'Check a secret provider configuration', which repeats the title, and adds the HTTP method and authorization class. However, it does not differentiate from similar sibling tools like pc_get_companies_by_company_id_secret_providers_health, which might have overlapping functionality.
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 does not specify prerequisites, such as needing a valid secret provider config ID, or contexts where this check 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?
Annotations indicate the operation is not read-only, but the description does not elaborate on behavioral traits such as whether rotation invalidates the previous secret, requires specific permissions, or has side effects. It adds minimal 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded with the title and endpoint, but it sacrifices informative content for brevity. It could be expanded to include key details 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?
Despite having an output schema that may document return values, the overall description lacks essential context for a mutation tool. It fails to explain the concept of rotation, preconditions, or what happens to old secret values, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 2 parameters (body and path) with 0% schema description coverage, yet the description provides no explanation of what these parameters represent. The agent is left to infer meaning solely from parameter names and structure, which is insufficient.
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 title and description clearly state 'Rotate a secret', which indicates the tool's purpose. However, it does not distinguish itself from sibling secret-manipulation tools like pc_patch_secrets_by_id or pc_delete_secrets_by_id.
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 only mentions the HTTP endpoint and authorization class, but fails to explain under what circumstances a secret should be rotated.
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 destructiveHint=true, and the description only adds the HTTP method and authorization class. It does not explain what stopping entails, side effects, or reversibility, adding minimal value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with two short sentences, but it omits crucial information that would be necessary for correct invocation. It is not overly verbose but lacks substance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature, the lack of parameter descriptions, usage context, and behavioral details makes it incomplete for an agent to use correctly without prior domain knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameters. The path parameter 'slotId' is implied but not described, and 'companyId' in body and query is not mentioned.
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 title and description clearly state 'Stop a gateway runtime slot', with a specific verb and resource. However, it does not explicitly differentiate from the sibling tool that restarts a slot, though the context makes it distinct enough.
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 when a slot should be stopped instead of restarted. No prerequisites or context are 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 indicate destructiveHint=true and readOnlyHint=false, so the agent already knows this is a destructive operation. The description adds no further behavioral context, e.g., whether revoking disconnects users, triggers side effects, or is irreversible. The 'Authorization class: board_or_agent' hint is present but minimal.
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 this is not necessarily concise—it lacks important details. The structure is minimal: repeat title, mention HTTP method, path, and auth class. Every sentence earns its place, but more content is needed. Score 3 for being adequate but not wasteful.
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 (2 params, nested object, output schema exists), the description is incomplete. It does not explain return values, behavior on success/failure, or parameter constraints. The output schema is present but not described. The description leaves too many gaps for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no parameter descriptions in schema). The description does not explain the purpose of 'companyId' in body or 'sessionId' in path. For a tool with two required parameters (one nested), this is insufficient. The agent cannot discern parameter roles or required formats.
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?
Description clearly states the action: 'Revoke a tool gateway session'. The verb 'revoke' and resource 'tool gateway session' are specific. However, it does not differentiate from siblings like post_tool_gateway_gateway_tokens_by_token_id_revoke, which also revokes something. Still clear enough for basic purpose.
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 on when to use this tool vs alternatives. There are sibling tools for revoking tokens and managing sessions, but the description gives no context about when to revoke a session vs token, or prerequisites (e.g., session must be active). Only mentions authorization class, which is not usage guidance.
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 traits beyond annotations. It fails to mention side effects, error behavior, or the implications of the openWorldHint and destructiveHint=false annotations. No additional context 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief (two sentences) but includes a technical HTTP path and auth class that may not be relevant for an AI agent. It is concise but could be more structured and front-loaded with essential info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested object, 5 sub-parameters, no schema descriptions, output schema present), the description is woefully incomplete. It lacks examples, return value hints, and any contextual framing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain any parameters. With 0% schema description coverage, this is a critical gap. The agent receives no guidance on the meaning of 'tool', 'parameters', 'timeoutMs', 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 states 'Execute a tool through the gateway', which clearly indicates the tool's action and resource. It distinguishes from sibling tools that perform other gateway operations (e.g., sessions, tokens) but lacks specificity about what a 'tool' is in this context.
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 over alternatives. It only includes the HTTP path and authorization class, omitting any context about typical use cases 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 this is a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds minimal behavioral context: it's a POST operation and requires 'board' authorization. It does not disclose side effects, such as whether duplicate entries are allowed, whether entries can be overwritten, or what happens if validation fails. Given the annotations cover the safety profile, the description provides marginal added value.
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 it is structured with a clear purpose line followed by a reference line. However, given the complexity of the tool (multiple parameters, nested objects), it is under-specified. A concise but more informative description would be better.
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 zero parameter documentation in both schema and description, the tool is incomplete for effective use. The description does not explain return values even though an output schema exists. It leaves the agent to infer input semantics from the API path and parameter types alone, which is insufficient for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, meaning no parameter descriptions exist. The tool description itself adds no information about parameters. The schema include complex nested fields like 'body' with selectors, effects, and conditions, but the agent is left without any guidance on how to construct the request body. This is a critical gap that severely hinders correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create a tool access profile entry'. This is a specific verb+resource pair. However, it does not distinguish this tool from sibling tools that also operate on tool profiles, such as pc_patch_tool_profile_entries_by_entry_id or pc_post_tool_profiles_by_profile_id_duplicate.
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 prerequisites (e.g., needing an existing profile), or when to use other operations like patching or deleting entries. The only contextual hint is the HTTP method and authorization class, which is insufficient.
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 authorization class and HTTP method, which is useful context. There is no contradiction, and the description adds some behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very brief, consisting of one phrase and a technical line. It is efficient and front-loaded, but lacks supporting structure. It is concise but not sufficiently informative.
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 an output schema exists (not shown), the description fails to explain what 'quota-windows' are, how the report differs from other cost reports, or any key details. Given the tool's role among many similar siblings, the description is incomplete for informed selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of the single parameter (companyId). It does not clarify the parameter's meaning, format, or constraints, leaving the agent with no additional semantic information.
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 title 'Cost report: quota-windows' and the HTTP GET endpoint indicate the tool retrieves a cost report about quota windows. However, it does not explicitly state the verb or differentiate from similar cost-report siblings like 'costs_window_spend' or 'costs_summary', making the purpose somewhat vague.
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 mentions an authorization class ('board_or_agent'), but provides no guidance on when to use this tool versus alternative cost-report tools. With many sibling tools, the lack of usage context reduces its usefulness for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, etc., and the description adds only 'Authorization class: board.' No additional behavioral traits (e.g., error handling, file existence behavior) are disclosed. This is adequate but minimal.
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 (two sentences, no fluff), but it sacrifices necessary detail. For a tool with zero schema descriptions, this structure is too sparse.
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 presence of an output schema, nested parameters, and multiple optional fields, the description is insufficient. It doesn't explain what the output contains, how workspace selection works, or how this tool fits into the file resource workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it provides no explanation of any parameter. The query parameters (path, projectId, workspace, workspaceId) are entirely unexplained, leaving the agent without guidance on how to use them.
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 repeats the title verbatim and adds the HTTP path, but it doesn't distinguish this tool from siblings like 'list' or 'resolve' beyond the name. It lacks specificity about what 'content' means (text, binary, etc.).
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 on when to use this tool versus alternative file-related tools (list, resolve). No when-to-use or when-not-to-use context provided.
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 'Archive' without explaining what it entails (e.g., reversibility, effect on related data). Annotations already indicate destructiveHint:true, but the description adds no behavioral detail beyond that.
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) and contains no unnecessary words. However, it is too minimal to convey useful information, making it under-informative rather than efficiently 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 complexity of the tool (destructive, with output schema and multiple parameters), the description lacks essential context such as what archiving means, what happens after archiving, and the authorization requirements beyond mentioning 'board'. It is not sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the parameters. The schema has partial coverage (body has a description, but connectionId lacks one). The description should clarify the connectionId parameter but does not.
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 archives a tool connection, using a specific verb and resource. However, it does not distinguish this operation from sibling tools like pc_patch_tool_connections_by_connection_id or pc_post_tool_connections_by_connection_id_reconnect.
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. There is no mention of prerequisites, context for archiving, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, covering safety. The description adds the endpoint and authorization class, which provides some behavioral context beyond annotations, but does not disclose additional traits like side effects or response details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very brief with only two short sentences and a line. While it avoids fluff, it is under-specified and fails to convey necessary information about parameters and usage, sacrificing completeness 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 the tool has an output schema (not required to describe return values), the description still lacks parameter semantics and usage guidance. For a simple one-parameter tool, the description is incomplete and leaves the agent unsure how to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter (path.id) is not described in the schema (0% schema description coverage) and the description does not explain its purpose or format. The agent ID is mentioned only implicitly in the endpoint path. This is a critical gap for correct usage.
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 retrieves agent configuration with 'Get agent configuration'. It also specifies the HTTP method and path. However, it does not distinguish this tool from sibling tools like pc_get_agents_by_id or pc_get_agents_by_id_runtime_state, which also retrieve agent data.
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 an authorization class ('board_or_agent'), giving some context on who can use it, but it offers no guidance on when to use this tool versus alternatives, nor any prerequisites or usage scenarios.
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, idempotentHint, and destructiveHint, so the description adds little behavioral context beyond the API path and auth class. It does not disclose potential error states or edge cases.
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 concise, with two sentences. It efficiently states the purpose and includes the API operation details without extraneous text.
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 good annotations, the description lacks context about what constitutes runtime health, what alert recommendations entail, and how to interpret the results. More detail would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for the only parameter (companyId). The tool description does not explain what companyId is or how to obtain it, failing to compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool summarizes MCP runtime health and alert recommendations. It uses a specific verb and resource, distinguishing it from siblings like pc_get_health which is a general health check.
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 the API path and authorization class but gives no guidance on when to use this tool versus alternatives. It does not mention prerequisites, when not to use, or how it relates to other health-related 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?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds only the authorization class 'board_or_agent' and the endpoint, which provides minimal additional 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (two sentences) and front-loaded, but it is overly minimal, lacking detail that would justify its 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 simple 1-param read-only tool with an output schema, the description should at least hint at what the log contains (e.g., timestamps, events). It fails to provide this context, making it 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?
The input schema has one parameter (path.runId) with 0% schema description coverage. The description does not explain what runId is or provide examples, so it adds no 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 verb and resource: 'Get log for a heartbeat run'. It helps distinguish from siblings that get other aspects (events, issues, etc.), though it does not explicitly differentiate.
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 the HTTP method and path, but offers no guidance on when to use this tool versus alternatives like pc_get_heartbeat_runs_by_run_id (which gets run info). No prerequisites or exclusions 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?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds the HTTP method and authorization class (public), which provides minimal extra context but does not explain what 'test' entails (e.g., whether it validates token format or checks actual resolution).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very brief (two lines), repeating the title and providing the endpoint. It under-specifies important details, sacrificing informativeness 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?
Although an output schema exists, the description does not indicate what the test returns (e.g., success/failure, resolved user/company). Combined with missing parameter semantics, the description fails to give the agent sufficient context for proper invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter (token) with 0% schema coverage (no description). The description does not mention the token parameter at all, so it adds no value beyond the schema. For a test operation, format or constraints are critical.
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 'Test invite token resolution' and provides the HTTP endpoint, indicating a specific verb (test) on a resource. However, it does not explicitly differentiate from sibling tools like pc_get_invites_by_token or pc_post_invites_by_token_accept, leaving 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 on when to use this tool versus alternatives such as pc_get_invites_by_token (which likely retrieves invite details) or pc_post_invites_by_token_accept (which accepts). The description lacks any context about prerequisites or scenarios.
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, destructiveHint=false, which cover safety. The description adds the authorization class and endpoint, but does not disclose any additional behavioral traits (e.g., error handling, pagination, or content of results). With annotations present, the bar is lower, but the description adds minimal extra value beyond structured data.
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, it is terse and lacks explanatory detail that would benefit the agent. It is not overly verbose, but it could include more value without being wordy.
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 a simple input (pluginId only), annotations covering read safety, and an output schema (context signal), the description provides the minimum necessary information. However, it omits context about what 'jobs' are in this domain, how many jobs might be returned, or any constraints. It is adequate but not complete for a rich understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, meaning no parameter descriptions are provided within the schema. The tool description does not add any meaning to the single parameter (pluginId beyond its type. The agent gets no guidance on what values are valid or what the parameter represents.
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 'List' and resource 'plugin jobs', and provides the API endpoint and authorization class. However, it does not explicitly differentiate from sibling tools like pc_get_plugins or pc_get_plugins_by_plugin_id, but the name and title make the purpose reasonably 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?
No guidance on when to use this tool versus alternatives. The description lacks context about prerequisites, typical use cases, or scenarios where other tools might be more appropriate. It only states the basic 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 readOnlyHint false (update operation) and destructiveHint false. The description adds the authorization class, which is useful behavioral context. However, it does not disclose side effects, idempotency (hinted false), or other traits beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two sentences) and easy to parse, but is overly terse. It earns its place for conciseness but sacrifices critical parameter and usage details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the input schema (many nested fields), the description is severely incomplete. It fails to explain the purpose of body fields, the effects of updating different properties, or what the output schema contains. The annotations and output schema do not compensate for this lack of context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description needed to explain the parameters but only mentions the endpoint. The body field has many properties (name, status, etc.) with no descriptions, leaving the agent without guidance on their meaning or usage.
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 'Update a company' with the HTTP method and endpoint, making the verb and resource explicit. It distinguishes from read and delete siblings but does not explicitly differentiate from the similar branding patch tool.
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 the authorization class ('board_or_agent'), but no guidance on when to use this tool versus alternatives like the branding-specific patch. It lacks explicit when-to-use or when-not-to-use 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?
Annotations already indicate that the tool is not read-only, not idempotent, and not destructive. The description adds only the authorization class ('board_or_agent'), which is a minor behavioral detail. It does not explain side effects, required permissions beyond the class, or call 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 extremely short and front-loaded, but this conciseness sacrifices completeness. It fits in a single line but lacks necessary details, so it is not a model of effective 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 the 0% schema description coverage and lack of output schema description, the description is insufficient. The agent cannot understand the tool's full capabilities, parameter constraints, or return values, making it incomplete for effective usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet no parameter explanations are provided. The 'status' enum (open/resolved) in the body is not defined, nor are the path parameters (id, key, threadId). The agent cannot determine valid values or usage from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a document annotation thread', which identifies the verb and resource. However, it does not differentiate from sibling tools like POST (create) or GET (read) annotations, limiting its distinctiveness.
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., POST for creating, GET for retrieving). The description only includes the HTTP method and authorization class, offering no context on typical use cases.
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 readOnlyHint=false (modifies state) and destructiveHint=false (not destructive), which the description does not contradict. The description adds that it is a PATCH operation and the authorization class. However, it fails to disclose potential consequences, such as whether changing status to 'deleted' might be irreversible or trigger other effects.
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, which can be concise, but it lacks necessary details. The structure places the title on one line followed by two lines of implementation details (HTTP method and auth). It is not front-loaded with the most important information for an agent; it prioritizes technical details over usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 required parameters, nested objects, enums, and an output schema, the description is severely incomplete. It does not explain input/output, constraints, or behavior. The agent cannot use this tool effectively without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining parameters. It does not describe any parameter, not even the required 'id' or the body fields like 'key', 'name', 'status'. The schema provides constraints (e.g., pattern, maxLength) but no semantic meaning. This is a significant gap.
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 title and description clearly state 'Update a secret', which identifies the verb (update) and resource (secret). Among sibling tools, there are create, delete, and rotate secret tools, so this tool is distinct. However, the description does not specify that it performs a partial update via PATCH, which is implied but not explicitly stated.
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 creating, deleting, or rotating secrets. It only includes an authorization class note, which is a security detail, not usage guidance. The agent is left to infer the appropriate 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?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description adds minimal value. It mentions the HTTP method and authorization class but no behavioral traits beyond what annotations cover. No contradiction, but insufficient 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the purpose, but it is overly terse. It omits essential information, making it less useful despite its brevity. It could be more informative while remaining concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with a complex input schema (2 parameters, many nested fields) and no schema descriptions, the description is severely incomplete. It does not mention return values (output schema exists but is not referenced), required fields, or any usage context. The tool is not adequately documented for reliable agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, leaving the description to compensate for undocumented parameters. The description does not explain any parameter meanings, constraints, or relationships. The complex body schema with many fields remains entirely unexplained, severely hindering correct invocation.
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 explicitly states 'Update a work product' with a specific verb and resource, clearly distinguishing from sibling tools like pc_post_issues_by_id_work_products (create) and pc_delete_work_products_by_id (delete). The title also reinforces the purpose.
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 on when to use this tool versus alternatives. The description lacks context on prerequisites, typical scenarios, or exclusions. It only provides technical details (HTTP method and authorization class) which do not help with usage decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds authorization class 'board_or_agent', which is helpful but not present in annotations. However, it does not disclose side effects, safety implications, or what happens during reload, leaving behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (two short lines) and front-loaded with the action. However, it is too brief to be fully effective, missing critical details while occupying minimal space.
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 a nested input schema and output schema, the description omits any explanation of the response, the body parameter, or the reload effect. In the context of many sibling tools, it fails to provide enough context for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no information about parameters beyond the schema. The path parameter 'type' is undocumented in the schema and description. With schema coverage at 50%, the description fails to compensate by explaining parameter meaning or constraints.
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 states 'Reload an adapter' with the HTTP method and path, providing a verb+resource. However, it does not clarify what 'reload' entails (e.g., configuration refresh, restart) or distinguish it from siblings like 'reinstall' or 'update', making the purpose somewhat vague.
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 pc_post_adapters_by_type_reinstall or pc_patch_adapters_by_type. The description lacks any usage context, prerequisites, or scenarios.
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 non-readonly and non-idempotent behavior, but the description adds minimal additional context. It mentions an authorization class (board_or_agent) which is useful, but does not explain side effects, error conditions, or what 'approve' entails 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (two lines), which has the benefit of brevity but at the cost of necessary detail. It is front-loaded with the title, but the structure is minimal and could be improved by adding brief usage context.
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 existence of many sibling approve tools and an output schema, the description is too sparse to fully guide an AI. It lacks context about the approval workflow, dependencies, and how this tool fits into the broader system. The annotations provide some behavioral hints, 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?
The input schema has 50% description coverage, but the description adds no parameter-level details. The 'id' parameter is not explained (e.g., that it is the agent ID), and the optional body parameter remains vague. The title implies the resource, but explicit parameter documentation is missing.
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 title and description clearly state that the tool approves a pending agent action, and the operation path '/api/agents/{id}/approve' confirms the agent context. However, it does not explicitly distinguish this from other approve tools (e.g., for issues or CLI auth), leaving some 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 on when to use this tool versus sibling approve tools like pc_post_approvals_by_id_approve or pc_post_cli_auth_challenges_by_id_approve. The description lacks preconditions or context for invocation.
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 readOnlyHint=false and destructiveHint=false indicate mutation but not destruction, yet the description adds no behavioral context beyond the HTTP method and authorization class. It does not explain side effects, idempotency, or safety implications.
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 short but repeats the title. It could be more concise by removing redundancy, though it is not overly verbose.
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 (context signal), the description does not mention the return value or behavior. It fails to provide complete context for an agent heartbeat 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?
With schema description coverage at 50%, the description adds no extra meaning to parameters. The 'body' parameter is documented in the schema, but the 'path.id' parameter lacks description both in schema and description. No parameter details are provided in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'invoke' and resource 'agent heartbeat', and provides the HTTP method and path. However, it does not explain what invoking a heartbeat actually does functionally, which slightly reduces 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?
No guidance is given on when to use this tool versus alternatives (e.g., wakeup, pause, resume). The description lacks any context about appropriate usage scenarios 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 provided (readOnlyHint=false, etc.), but the description adds minimal behavioral context beyond stating the authorization class. It does not explain whether sync is additive, replaces all skills, or handles conflicts. The term 'sync' is ambiguous without further detail.
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 short but repeats the title in the first sentence. It could be more concise by not repeating. However, it is not overly verbose and gets to the point quickly. It earns a 3 for being adequate but not optimal.
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 2 required parameters, nested objects, and an output schema, the description is insufficient. It does not explain what the output contains, how the sync works, or any side effects. For an AI agent to use this tool confidently, more context 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 has 0% description coverage, and the description adds no parameter explanations. The schema shows 'desiredSkills' can be strings or objects with key/versionId, but the description does not clarify the format or semantics. The title hints at 'desired skills' but fails to provide meaningful guidance.
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 'Sync desired skills onto an agent configuration', which clearly identifies the action (sync) and the resource (desired skills on an agent). It is distinct from sibling tools like get_skills_catalog or get_skills_available. However, it does not elaborate on what 'sync' means in contrast to other skill modification operations.
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 on when to use this tool versus alternatives. There is no mention of prerequisites (e.g., agent must exist, skills must be available) or scenarios where this tool is appropriate. The description only states the operation, not 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 description adds minimal behavioral context beyond annotations. It does not explain side effects, required permissions, or what happens upon hire. The annotations already indicate it's not read-only or idempotent.
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 but repeats the title 'Hire an agent' which is already in the title field. It could be slightly more concise but is not overly verbose.
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 complexity of the tool (many parameters, nested objects, no output schema), the description is incomplete. It lacks essential context about the request body, response, and what constitutes a successful hire.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% meaning the description does not explain any parameters. The input schema has many nested properties but the description provides no meaning or guidance for them.
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 'Hire an agent' and provides the HTTP method and path. However, it does not explicitly distinguish this tool from sibling agent-related tools like 'pc_post_companies_by_company_id_agents'.
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. There are no prerequisites, context, or exclusion details provided.
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 include openWorldHint=true, but the description does not elaborate on what side effects or external state changes occur during creation. It neither confirms nor contradicts the annotations; it simply restates the action. The description adds no behavioral context beyond the annotations themselves.
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 but at the expense of necessary detail. It lacks structured breakdown of parameters or behavior. It could be more informative without becoming verbose, but it is not 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 complexity of the input schema with many nested fields and an output schema that is available but not described, the description is woefully incomplete. It does not help the agent understand how to construct a valid request, what the return value looks like, or any constraints on the environment creation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameters or their meaning. The schema is complex with nested objects (e.g., envVars, config), but the description provides no guidance on how to fill these fields, leaving the agent to infer from schema structure alone.
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 title 'Create an environment' and the first sentence clearly indicate the tool creates an environment for a company. Among sibling tools like pc_get_companies_by_company_id_environments, pc_patch_environments_by_id, and pc_delete_environments_by_id, this tool's purpose is distinct as a create operation. However, it does not explicitly differentiate its scope from similar create tools, but the verb 'create' is sufficient.
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 only mentions the authorization class 'board_or_agent' but provides no guidance on when to use this tool versus alternatives, such as when to create an environment via this endpoint versus other environment-related tools. No prerequisites, when-not-to-use, or alternative tool references 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 this is a mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds the authorization requirement, which is useful but does not disclose other behaviors like idempotency or error conditions.
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 to the point, but it omits essential parameter information, making it under-specified rather than concise. It could be structured better to include parameter details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the input (nested objects, many optional fields, enums) and low schema coverage, the description is far from complete. It does not explain the structure or requirements, leaving the agent without enough information to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate but does not. It provides no explanation of the body or path parameters, their required fields, or the meanings of properties like level, status, or parentId. This is a critical gap.
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 'Create a goal' and includes the HTTP method and endpoint, making the primary purpose clear. However, it does not differentiate from sibling tools like pc_patch_goals_by_id (update) or pc_delete_goals_by_id (delete), relying solely on the verb.
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 mentions an authorization class ('board_or_agent'), providing some guidance on who can use it. However, it lacks any context on when to use this tool versus alternatives, prerequisites, or typical scenarios.
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 readOnlyHint=false, idempotentHint=false, destructiveHint=false, establishing a write operation with potential side effects. The description adds the authorization class ('board') and the exact HTTP method/path. Beyond that, it does not disclose key behavioral traits (e.g., whether invites trigger notifications, if they are reversible, or what the response contains).
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 short (two sentences) and front-loads the purpose. However, it sacrifices completeness for brevity; critical parameter details and usage context are omitted, making it less effective than a slightly longer but more informative description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has nested parameters and an output schema, the description is far from complete. It fails to explain the meaning of the body fields, the purpose of each parameter, or what the response represents. The agent would struggle to invoke this tool correctly without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description provides no explanation of the parameters (body fields like humanRole, agentMessage, allowedJoinTypes). The agent has no guidance on how to populate these fields or what values are valid.
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 title and description clearly state 'Create a company invite', indicating the action (create) and resource (company invite). The description also provides the exact endpoint, distinguishing this creation operation from related list/read operations like pc_get_companies_by_company_id_invites. However, it does not elaborate on what an invite represents or the scope of the creation.
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 join requests or revoking invites. The agent is not told under what circumstances to create an invite or how it differs from similar actions.
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 destructiveHint=true, and the description adds the authorization class and HTTP method. However, it does not disclose the actual consequences (e.g., whether member is removed from active lists, if reassignment is required, or if the action is reversible). The description adds minimal value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with two sentences. The first sentence defines the action, and the second provides technical details. While efficient, it lacks structure (e.g., bullet points) and could be better organized for readability.
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 (destructive operation, nested objects, no output schema shown), the description is incomplete. It does not explain the effect of archiving, error conditions, or how to properly use the reassignment field. The agent cannot confidently invoke this tool based solely on the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description provides no explanation of the parameters (path, body) or the reassignment object. The agent receives no guidance on required fields or the meaning of the nested schema, leaving the tool difficult to use correctly.
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 ('Archive a company member') and provides the HTTP endpoint, which distinguishes it from other member tools like patch or get. However, it lacks detail on what archiving entails (e.g., reversible, impact on assignments) compared to similar 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 given on when to use this tool versus alternatives (e.g., updating or deleting a member). The description does not specify prerequisites or context for using this operation.
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 and destructiveHint=false, but the description does not explain what 'audit' entails—whether it creates a record, triggers a check, or returns something. The only extra detail is the authorization class, which is insufficient for understanding side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence plus endpoint info), which is concise but lacks necessary detail. It is front-loaded with the purpose, but the brevity comes at the cost of completeness.
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 operation is a POST audit with an output schema, the description should explain what the audit does and what is returned. It fails to do so, leaving the agent to infer the behavior from the tool name alone. Sibling tools are numerous, but no context is provided for decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description adds no meaning to the parameters. The 'body' parameter is required but described only as 'additionalProperties: {}' with no guidance on expected fields. The path parameters (companyId, skillId) are not explained beyond their types.
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 'Audit a company skill' which is a clear verb+resource. The title and name indicate the specific action of auditing a skill, distinguishing it from other skill CRUD operations like get, patch, delete. However, it doesn't explicitly differentiate from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 other skill operations. There is no indication of prerequisites or context such as requiring the skill to already exist.
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 'Star a company skill' but does not disclose behavioral details beyond what annotations provide. It doesn't mention whether starring is idempotent (annotations say idempotentHint=false), what happens if already starred, or any side effects like notifications. Annotations already give readOnlyHint=false and destructiveHint=false, so the description adds minimal value.
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 very concise (two short sentences). The first sentence restates the title; the second provides the HTTP method and auth class. While it avoids verbosity, it omits critical details. It is front-loaded but lacks structured breakdown for easy parsing.
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 role in skill management, the description is incomplete. It does not mention the response (though an output schema exists but is not provided), prerequisites (e.g., skill must already be associated with the company), or how this operation fits with other skill operations like listing, deleting, or updating stars. An agent might misuse it without these cues.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate by explaining parameters, but it does not. The path parameters (companyId, skillId) are named intuitively but not clarified (e.g., expected format). The body parameter is an arbitrary object with no guidance on its purpose (likely empty for starring). This severely limits an agent's ability to correctly invoke the tool.
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 verb 'Star' and the resource 'a company skill', effectively conveying the tool's purpose. The title reinforces it. Although it doesn't explicitly differentiate from the delete-star sibling, the HTTP method POST implies addition, which is clear enough.
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 the delete-star counterpart (pc_delete_companies_by_company_id_skills_by_skill_id_star) or other skill operations. There is no mention of prerequisites, such as the skill needing to exist or the user requiring specific permissions.
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 readOnlyHint=false, destructiveHint=false. The description adds the authorization class and endpoint details, but does not disclose behavioral traits beyond what annotations provide. No contradiction found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short, but this conciseness sacrifices necessary detail about parameters and usage. It is not efficiently informative; every sentence could carry more 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?
Given the tool has a nested input schema, output schema (not shown but present), and 2 required parameters, the description is incomplete. It does not explain what previewing means, what the response contains, or how the mcpJson should be structured.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain the purpose or format of the required parameters (path.companyId, body.mcpJson). The schema shows mcpJson accepts string or object, but no guidance on what constitutes valid input.
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 states 'Preview MCP JSON import' which provides a verb and resource, but it is vague and does not differentiate from sibling tools like pc_post_companies_by_company_id_imports_preview or pc_post_companies_import_preview. The endpoint is given but does not clarify the 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description only mentions the API operation and authorization class, lacking any context about prerequisites, limitations, or comparison with similar 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 this is a write (readOnlyHint=false) and non-destructive (destructiveHint=false) operation. The description adds the authorization class, which is a behavioral detail beyond annotations. However, it does not disclose side effects, success outcomes, or error scenarios.
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 lines) and front-loads the purpose. It lacks detail but is concise. It could earn its place better by including parameter hints or usage notes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple nested parameters, conditions, policy types) and the presence of an output schema, the description should explain what a tool policy is, what each major field does, or provide an example. It does none of this, leaving the agent with insufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about the parameters (path or body). The schema is complex with many nested fields, and the description adds no meaning to help an agent fill them correctly.
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 ('Create') and resource ('tool policy'), and the title reinforces it. The sibling list includes a GET for policies, so the create counterpart is distinguishable. However, it does not explicitly describe the scope (e.g., per company) beyond the endpoint path.
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 mentions 'Authorization class: board' which gives some access context, but it does not guide when to create a policy vs. reorder, patch, delete, or other sibling tools. No prerequisites, conditions, or alternatives are provided.
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 non-read-only, non-destructive, non-idempotent mutation with possible side effects (openWorldHint=true). The description adds only the authorization class ('Authorization class: board') but does not disclose behavioral details like duplicate handling, template creation limits, or whether the operation is synchronous. The description adds minimal 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very brief (two sentences), but it is not well-structured. The first sentence merely repeats the title, while the second provides the HTTP path and auth class. While concise, it lacks critical information and does not follow a useful structure (e.g., behavior, parameters, examples).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested objects, required fields, pattern constraints, and an output schema), the description is completely inadequate. It fails to explain the purpose of any input fields, the expected output, or side effects. The agent cannot effectively use this tool without external documentation or schema descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions exist in the input schema. The description does not describe any parameters, leaving the agent to interpret complex fields like 'args', 'tools', 'envKeys', 'templateId', 'command', and 'description' solely from their names and types. This is a severe omission for a tool with nested objects and required fields.
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 title and description clearly state the action 'Create an approved stdio MCP template'. The HTTP path and method are provided, distinguishing it from sibling tools like the GET listing (pc_get_companies_by_company_id_tools_stdio_templates) and the import tool (pc_post_companies_by_company_id_tools_mcp_import_json). The verb 'Create' accurately 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 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 authorization requirements (e.g., 'board' class), prerequisites, or contraindications such as using the import endpoint for JSON templates. The agent is left to infer context from the tool name and sibling names.
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 mark it as destructive (destructiveHint: true). The description adds the HTTP method and path but no behavioral details like irreversible effects, expectations, or side effects. Minimal value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, directly front-loaded with the action. No unnecessary words, though missing critical detail is not a conciseness issue per se.
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?
Lacks explanation of return values (despite output schema), error cases, prerequisites (e.g., existence of a trust rule), or post-conditions. Incomplete for a destructive operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameters. The reason, companyId, policyId are not described, leaving the agent uninformed about how to populate them.
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 'Revoke a tool trust rule,' with a specific verb and resource. While it doesn't elaborate on what a trust rule is, the title reinforces the purpose, making it clear among many sibling operations.
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 on when to use this tool versus alternatives like listing or creating trust rules. Only 'Authorization class: board' is provided, which is a prerequisite but not usage direction.
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?
Beyond the annotations (destructiveHint=true), the description adds no behavioral context. It does not explain what canceling entails, whether it is reversible, or any side effects. The description merely repeats the tool's name without elaboration.
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 concise, with two short sentences front-loading the purpose. However, it is overly brief and omits important details that could be included without significant bloat.
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 that the tool has an output schema and annotations, the description is too minimal. It does not explain the output, the effect of cancellation, or the required context. For a destructive operation, more thorough guidance is expected.
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 description adds no information about parameters. The input schema includes a required runId and an optional body, but the description does not explain their purpose or usage. With 50% schema description coverage, the description fails to compensate.
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 verb 'Cancel' and the resource 'heartbeat run', distinguishing it from sibling tools that operate on heartbeat runs in other ways (e.g., get, events, log). The mention of the HTTP method and path adds 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 does not provide any guidance on when to use this tool versus alternatives. It lacks prerequisites (e.g., the run must be active) and exclusions, leaving the agent without context for appropriate usage.
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 mutation, but the description adds no behavioral details beyond the endpoint. It does not explain what happens upon retry, side effects, or required permissions beyond 'board_or_agent'.
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 short and front-loaded, but it is too brief, omitting important information. It is concise but not sufficiently informative.
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 mutation, output schema, nested objects, and requires authorization, the description is incomplete. It fails to explain outputs, effects, or constraints, forcing reliance on the tool name.
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 description does not describe any parameters. The schema has a 'body' with a minimal description, and the 'path.id' is undocumented. Schema coverage is 50%, but the description adds no 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 title and description clearly state the verb 'Retry' and the resource 'scheduled issue run', and the endpoint gives specific context. However, it does not elaborate on what a 'scheduled issue run' is or distinguish it from other retry-related tools like 'recovery_actions_resolve'.
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 on when to use this vs alternatives, prerequisites, or conditions. The description only provides the endpoint and auth class, leaving the agent without decision 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 description adds the HTTP method (POST) and authorization class, which are not in annotations. However, annotations already indicate readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description does not elaborate on safety, idempotency, or potential side effects. The 'destructiveHint: false' is not explained further.
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 lines), which is concise. However, it sacrifices necessary detail. While it is structured with the operation path, it lacks meaningful content to guide usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two complex parameters (nested objects), no output schema explanation, and a high number of sibling tools, the description is severely incomplete. It does not explain return values, side effects, or how to use the configJson parameter. The agent cannot effectively invoke this tool without additional information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It does not describe companyId (which company?) or configJson (what structure? keys? values?). The configJson is an object with additionalProperties, but no guidance on valid fields. This leaves the AI agent with no clue on how to construct the request body.
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 title 'Set company-scoped plugin config' clearly indicates the verb (set) and resource (company-scoped plugin config). The description repeats this and provides the operation path, distinguishing it from sibling tools like pc_get_plugins_by_plugin_id_config (GET) and pc_post_plugins_by_plugin_id_config_test (test).
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 mentions the operation path and authorization class ('board'), but does not provide guidance on when to use this tool versus alternatives, nor does it specify prerequisites or when not to use it. No context for proper invocation 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?
The description adds no behavioral details beyond annotations. The annotations indicate readOnlyHint=false and destructiveHint=false, but the description does not clarify what 'test' entails (e.g., side effects, validation behavior). The openWorldHint=true suggests possible external effects, but these are not explained.
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 very concise with two sentences. The first sentence is front-loaded and clear. The second sentence provides internal operation details that may not be useful for an AI agent, but overall it is minimally worded.
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 complexity (2 required parameters, nested objects) and low schema coverage, the description is insufficient. It does not explain what testing does, how it relates to other plugin config tools, or what the output schema contains. An output schema exists, but the description still lacks context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not elaborate on parameters. It only mentions 'company-scoped', which implies companyId, but does not describe configJson or path. The description fails to add 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 states 'Test company-scoped plugin config', clearly indicating the verb (test) and resource (plugin config). It differentiates from sibling tools like pc_post_plugins_by_plugin_id_config by emphasizing the testing aspect.
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. It does not explain the purpose of testing (e.g., validation vs. actual application) or when to use the sibling pc_post_plugins_by_plugin_id_config 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?
Annotations indicate destructiveHint=true and readOnlyHint=false, but the description adds no behavioral details (e.g., what is overwritten, whether the restoration is reversible, or what happens to current state). The description merely restates the function title, relying entirely on annotations for safety cues.
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) and front-loaded with the purpose. It is concise but sacrifices informativeness. While no unnecessary words exist, the brevity leaves out important context that would 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?
Despite having 2 parameters, an output schema, and destructive behavior, the description is minimal. It does not explain the output, side effects, or any prerequisites. The tool is a restore operation, but the description fails to clarify what 'restore' entails (e.g., overwrites current? creates new revision?). More detail is needed for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema contains two parameters (path with id and revisionId) and an optional body, but schema description coverage is only 50% (body has a description, path properties do not). The description adds no parameter explanations, leaving the agent to infer that 'id' is the routine ID and 'revisionId' is the revision to restore. No extra semantics are 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 'Restore a routine revision' which directly indicates the action and resource. It includes the HTTP method and path, making it unambiguous. However, it does not explicitly differentiate from sibling tools like pc_get_routines_by_id_revisions (which lists revisions) or similar rollback tools, leaving the agent to infer uniqueness.
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 the authorization class 'board_or_agent' which hints at eligibility, but gives no guidance on when to use this tool versus alternatives, when not to use it, or what prerequisites exist. There is no mention of the context for restoration (e.g., after a bad change) 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 readOnlyHint=false, consistent with firing an action. The description adds the HTTP method and authorization class, but does not disclose side effects, idempotency, or what happens when the trigger is fired (e.g., starts a routine run). Behavioral traits beyond annotations are mostly absent.
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 short (two sentences), but the first sentence redundantly repeats the title. It is not overly verbose, but could be more efficient by omitting the repetition.
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?
Even though an output schema exists, the description does not mention what the tool returns (e.g., confirmation of firing, a run ID). For an action tool, this is incomplete. The context is insufficient for an agent to understand the full outcome.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 50% schema coverage, the description adds that the body is an 'Optional JSON compatibility payload' with no declared schema. The path parameter (publicId) is not described. The description adds minimal 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 states 'Fire a public routine trigger', which is a clear verb+resource. The HTTP path reinforces the purpose. However, it does not differentiate from sibling tools like pc_post_routines_by_id_run or pc_post_routines_by_id_triggers, which may have overlapping functionality.
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 does not mention prerequisites, constraints, or scenarios where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the HTTP method (POST) and path, plus authorization class, beyond annotations. However, it does not describe side effects, what happens during a test call, or the nature of the operation. Annotations indicate non-read-only and non-destructive, but no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short with two sentences, which is concise but under-specified. It could include more context without becoming verbose. Front-loading is fine but overall too sparse.
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 2 nested parameters, no parameter descriptions, and an output schema without explanation, the description is insufficient. It does not clarify the purpose of the test call, expected behavior, or how it differs from similar tools. The sibling list is large, making differentiation important.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning the description provides no parameter explanations. Parameter names like 'agentId' and 'toolName' are somewhat self-explanatory, but the 'parameters' object is undefined. The description fails to compensate for the low schema coverage.
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 states 'Run a tool connection test call', which is a clear action but nearly identical to the title. It lacks detail on what a test call involves and does not differentiate from sibling tools like 'pc_get_tool_connections_by_connection_id_test_calls_b_*'.
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 on when to use this tool versus alternatives. The description mentions authorization class but provides no context for appropriate usage 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 declare the tool is idempotent and non-destructive. The description adds the HTTP method and auth class, but omits important behavioral context like the fact it operates on the current user's membership (via 'me' in the path) and the effect of the 'starred' field.
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 but at the cost of omitting crucial details. It is not bloated, but some important information is missing.
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 (nested objects, enums, boolean parameter) and 0% schema coverage, the description is insufficient. It does not explain the scope (current user), required path parameters, or output format. An output schema exists but is not referenced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameters. The 'state' enum values are inferable but not explicitly described, and 'starred' is entirely unexplained. The description adds no value beyond the raw 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 'Join or leave an agent resource', which conveys the core action and resource. It distinguishes from the GET sibling (viewing memberships), but there is another PUT sibling with a similar name, and no differentiation is provided.
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 on when to use this tool vs. alternatives, no prerequisites, and no when-not-to-use conditions. The only additional detail is the authorization class, which is insufficient for decision-making.
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 tool as idempotent and non-destructive. The description adds the 'Authorization class: board' detail, providing some behavioral context. However, it does not disclose potential side effects or required permissions beyond that.
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 concise but overly minimal, repeating the title and adding only technical details. It is not verbose, but it could be more structured to include parameter hints or use cases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool with nested objects and many parameters, the description is severely lacking. It does not explain the role of a 'plugin local folder' or how this tool fits into plugin management, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fails to explain any parameters. Terms like 'path', 'access', 'requiredFiles', and 'requiredDirectories' in the body, as well as path parameters, are not described, leaving the agent without semantic guidance.
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 title and description clearly state 'Save a plugin local folder' and specify the PUT operation. However, it does not distinguish this tool from similar sibling tools like GET or POST operations for local folders, so purpose is clear but lacks 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?
No guidance is provided on when to use this tool versus alternatives (e.g., GET or POST for local folders). The description lacks context for usage decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds the authorization requirement ('board_or_agent'), which is useful. However, it does not describe side effects or what exactly is deleted beyond the generic statement.
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 concise (two short sentences) and to the point. The first sentence states the purpose; the second adds technical details. No wasted words.
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 destructive nature, the lack of parameter explanations and return value information leaves it incomplete. The description does not cover the body requirement or what happens after deletion.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of the parameters (path, body with path and target). The agent must rely solely on the schema, which lacks descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the resource ('a skill file or folder'). It is specific enough to differentiate from most sibling tools, though it does not explicitly distinguish from other delete operations on skills.
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., other file-related operations or delete tools). The description gives no context about prerequisites or 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 already indicate destructive and idempotent behavior (destructiveHint=true, idempotentHint=true, openWorldHint=true). The description adds the authorization class and HTTP method but does not explain side effects, what 'disable' entails, or what happens to running environments. The open world hint suggests undisclosed 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 very concise—two sentences that state the purpose and provide the HTTP operation and authorization. It is front-loaded with the main action. However, it is too brief to cover other dimensions, but for conciseness alone it earns a high 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?
Despite having 3 parameters (one nested object), an output schema, and being destructive with open world hints, the description fails to provide sufficient context. It does not describe the output, success/failure behavior, parameter details, or side effects. The output schema exists but is not leveraged in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 33% schema description coverage, the tool description does not explain the meaning of parameters. The body parameter's schema description is about the schema, not its purpose. The path (environmentId) and query (companyId, deleteProviderTemplate) parameters lack any explanation of their roles, leaving the agent to infer from schema structure alone.
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 title and description clearly state the tool disables the active environment custom image template, with the HTTP method and endpoint provided. It differentiates from sibling tools like environment deletion or template creation/retrieval. However, using 'disable' instead of 'delete' introduces slight ambiguity about the operation's permanence.
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., pc_delete_environments_by_id or the GET/POST for custom image templates). Prerequisites (e.g., environment must exist, template must be active) and consequences of multiple calls are not mentioned.
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 mark destructiveHint=true. The description adds that it is a DELETE operation, confirming destruction, but does not elaborate on consequences (e.g., irreversibility, impact on related data). 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) and front-loaded with the main action. The technical details are concise, though the second sentence adds minimal value for an agent.
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 presence of an output schema, return values need not be explained, but the description lacks important context such as prerequisites (e.g., plugin must exist, user must have board authorization) and typical use cases.
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 description does not mention any parameters. The input schema has two parameters (path with pluginId, optional body), and schema coverage is 50%. The description adds no 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 'Delete a plugin' which is a specific verb+resource. It matches the tool's name and title and conveys the main action. However, it does not differentiate from sibling tools that also operate on plugins.
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 technical details (HTTP method, path, authorization class) but offers no guidance on when to use this tool versus alternatives. No when-to-use or when-not-to-use context is 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?
The description adds the HTTP method and authorization class, but the core behavioral traits (destructive, idempotent) are already conveyed by annotations. No extra details are provided about side effects like cascading deletions or whether the operation can be undone.
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 very concise with two sentences, no unnecessary words. However, it sacrifices valuable context for brevity, missing opportunities to clarify parameters or behavior.
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 destructive tool with nested parameters and an output schema, the description is insufficient. It lacks information on parameter semantics, prerequisites, and the consequences of deletion, leaving significant gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain parameters. It does not. The agent is given no information about what 'force' means or how 'reassignToProfileId' works, leaving the agent to infer from schema alone.
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 verb 'Delete' and the resource 'tool access profile', which directly matches the title and distinguishes it from sibling tools like patch or create operations for profiles.
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 archiving or disabling a profile. It does not mention prerequisites, intended use cases, or scenarios where deletion is inappropriate.
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, idempotentHint=true, openWorldHint=true, so the description's 'Get' is consistent. The description adds the authorization class (board_or_agent), which provides some behavioral context but not essential beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences. The first sentence repeats the title verbatim, which is redundant but not overly verbose. It could be more concise by omitting the redundant sentence. Overall acceptable.
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 that an output schema exists, the description need not explain return values. However, it lacks explanation of what 'adapter registration details' includes and does not clarify the 'type' parameter's meaning or possible values. For a simple 1-param tool, the description is insufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter 'path' with nested 'type' (string, required). Schema description coverage is 0%, and the description does not explain what 'type' values are valid or what the parameter represents. No additional meaning is provided 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 title and description both say 'Get adapter registration details', which clearly indicates the tool retrieves details about adapters by type. It distinguishes from siblings like pc_get_adapters (list all) and pc_get_adapters_by_type_config_schema (config schema). However, it does not explicitly differentiate in the description.
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 does not provide any guidance on when to use this tool, when not to, or alternatives. It only includes the HTTP method and authorization class, which are more technical details than usage 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 convey read-only, idempotent, and non-destructive behavior. The description adds the HTTP method (GET) and authorization class ('board_or_agent'), which provides useful behavioral context beyond annotations. However, it does not disclose rate limits, error scenarios, or other behavioral 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 very short (two sentences) and includes only essential information. The first sentence echoes the title, which is slightly redundant. It is concise but not fully front-loaded with the most critical usage information.
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 that there is an output schema and annotations cover safety, the description could be adequate for a simple retrieval. However, the parameter is undocumented (schema coverage 0%), and the description does not clarify what the tool returns or potential prerequisites. The description leaves gaps that could confuse the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single parameter (path.id) with no description. The description does not explain what 'id' represents or how to obtain it. Schema coverage is 0%, so the description carries the full burden but provides no parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get an agent' which is a clear verb+resource, and specifies the endpoint GET /api/agents/{id}. However, it does not explicitly distinguish this from sibling tools like pc_get_agents_me or pc_get_companies_by_company_id_agents, which retrieve agents in different ways. The purpose is clear but not fully differentiated.
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. While sibling tools exist for getting the current agent (pc_get_agents_me) or listing agents (pc_get_companies_by_company_id_agents), the description provides no usage context or selection criteria.
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, idempotentHint, and destructiveHint, making the safe, read-only nature clear. The description adds the HTTP method and auth class, but does not disclose any further behavioral traits (e.g., error behavior, response details). With annotations covering the key safety aspects, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) and front-loads the purpose. However, the first sentence is redundant with the title. Still, it is concise and avoids unnecessary details.
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 is simple and has an output schema, the description still lacks crucial context: it does not clarify what a config revision is, how to obtain the `revisionId`, or what the response contains. This forces the agent to rely on external knowledge. Incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has two required parameters (`id` and `revisionId`) but no descriptions in the schema (0% coverage). The description does not explain what these parameters represent or provide any additional semantics. The agent is left to infer that `id` is the agent ID and `revisionId` is the revision identifier, which is insufficient for reliable invocation.
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 tool name and title clearly indicate it retrieves a specific agent config revision. The description restates this, but does not explicitly distinguish it from the sibling tool `pc_get_agents_by_id_config_revisions` (which lists revisions). This is clear but lacks explicit 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 the HTTP method and authorization class, which is helpful context, but it offers no guidance on when to use this tool versus alternatives like `pc_get_agents_by_id_config_revisions` or `pc_get_agents_by_id_configuration`. Missing when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 HTTP operation and authorization class, but does not elaborate on the returned runtime state or any behavioral nuances.
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 (two lines) and front-loaded. It could benefit from a slightly more structured format, but it is not verbose.
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 presence of an output schema and nested objects, the description is too brief. It fails to inform the agent about the output's nature, potential use cases, or prerequisites beyond the bare endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description provides no explanation for the required 'path.id' parameter. The agent ID is not clarified, leaving the agent unclear about what value to provide.
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 title and description clearly state 'Get agent runtime state', providing a specific verb and resource. However, it does not distinguish from sibling tools like pc_get_agents_by_id, which also retrieve agent data.
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 lacks context for appropriate usage scenarios 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?
Annotations already cover readOnly, openWorld, idempotent, and destructive hints. The description adds the authorization class ('board_or_agent'), which is useful context beyond annotations, but lacks other behavioral traits like error handling or response format.
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 very concise with two sentences. It front-loads the essential purpose and adds the endpoint and auth class. However, it could include more useful details without becoming verbose.
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 simplicity of the tool (one parameter), the description is incomplete. It does not mention the type of content returned (binary, text, etc.), error conditions, or how to obtain the assetId. The output schema may help, but the description still lacks key context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no explanation of the 'path' parameter or the 'assetId' field. The agent gets no additional meaning beyond the raw schema structure.
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 title and description clearly state 'Download asset content', which is a specific verb and resource. However, it does not differentiate this tool from other similar download tools among siblings, such as file resources content download.
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 the HTTP method and authorization class but offers no guidance on when to use this tool versus alternatives. There is no mention of 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description only adds the HTTP path and auth class. No additional behavioral details (e.g., error handling, pagination) are given, but the annotation coverage reduces the burden.
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 purpose, but it omits important information like parameter semantics. It is concise but at the cost of completeness.
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?
While an output schema exists, the description lacks context about the purpose of push runs, the relationship to other cloud upstream tools, and parameter descriptions. This makes it incomplete for an agent unfamiliar with the domain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description provides no explanation of the parameters (connectionId, runId, companyId). The agent must rely solely on parameter names, which may be insufficient, especially for 'companyId' not included in the path.
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 explicitly states the verb 'Get' and the resource 'a cloud upstream push run', making the purpose clear. However, it does not explicitly differentiate from sibling tools like POST push runs endpoints, though the verb 'Get' implicitly distinguishes as read-only.
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., other push run endpoints). The description only states the HTTP path and authorization class without context on usage scenarios.
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, destructiveHint=false, so safety is clear. The description adds authorization class ('board_or_agent') but does not elaborate on behavior beyond detection.
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 only two sentences, but the first is redundant with the title. It is concise but could be more informative within its length.
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 presence of an output schema and annotations, the description still lacks necessary context about what 'detect' returns and how to interpret results. The tool is simple but the description is inadequate for complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description provides no additional meaning for the 'path' object's 'companyId' or 'type' parameters. Both are required but undocumented, leaving the agent without guidance on valid values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb+resource: 'Detect active model for an adapter'. It distinguishes from sibling tools like listing models or testing, focusing on detection of the active model.
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 on when to use this tool versus alternatives (e.g., pc_get_companies_by_company_id_adapters_by_type_models). The description does not provide context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the HTTP method (GET) and authorization class ('board_or_agent'), which adds operational context. However, it does not describe pagination behavior, rate limiting, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two sentences) and front-loaded with the purpose. However, it omits crucial parameter details and usage context, making it less helpful. It is concise but underinformative.
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 complex input schema (nested path, 7 optional query params) and the existence of an output schema, the description does not provide enough context about filtering, grouping, pagination, or the nature of artifacts. It leaves the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It provides no information about any of the 7 optional query parameters (q, kind, limit, cursor, groupBy, projectId, groupIssueId) or the required companyId. The agent cannot infer parameter semantics from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The title 'List company artifacts' and description clearly state the tool's verb (list) and resource (company artifacts). It distinguishes itself from sibling tools by specifying the artifact listing scope, but does not elaborate on what constitutes an artifact.
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 on when to use this tool versus similar list operations (e.g., listing issues, projects, or other company resources). No context about prerequisites or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which cover safety and idempotency. The description adds the authorization class ('board_or_agent'), which is useful but does not disclose other behavioral aspects like result format, pagination, or potential limitations. Given rich annotations, the description adds marginal value.
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 (two sentences), which is concise, but it lacks structure: the title is repeated, and the technical details are crammed without clear separation. The information could be organized better for agent parsing, though it is not overly verbose.
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 does not explain what the 'by-agent' report contains (e.g., cost breakdown per agent, time ranges, aggregation). An output schema exists but is not referenced. Given the complexity of cost reports and many similar sibling tools, the description is insufficient for an agent to understand the tool's output or compare with alternatives.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one required parameter (companyId in path) with 0% description coverage. The tool description does not explain what companyId represents, expected format, or constraints. With no parameter documentation in either schema or description, the agent cannot determine correct usage.
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 'Cost report: by-agent', which clearly indicates it provides cost data grouped by agent. The HTTP method and endpoint path further clarify the operation. It is distinguishable from sibling cost tools (e.g., by-agent-model, by-provider) through the name, though the description could be more explicit about the grouping.
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 like costs_by_agent_model or costs_by_provider. The agent is left to infer from the name alone. The description does not provide context for selection, missing an opportunity to differentiate use cases.
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, idempotentHint, and destructiveHint false, covering safety and idempotency. The description adds the authorization class 'board_or_agent' and confirms it's a GET operation, providing useful but limited additional behavioral context. No mention of rate limits, pagination, or data freshness.
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, but it repeats the title verbatim. It could be more informative without adding length, such as explaining the report's content or parameter. Acceptable conciseness but lacks substance.
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 complexity of cost reporting and many sibling tools, the description is incomplete. It does not explain what the report outputs (though an output schema exists), how to differentiate from other cost tools, or any additional context like data scope or filters. The agent lacks sufficient information to use the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one required parameter (companyId) with no description in the schema (0% coverage). The description does not explain the parameter's meaning, format, or how to obtain it. The tool name and path imply it's a company ID, but no explicit guidance is given.
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 title and name clearly indicate this is a cost report grouped by agent model. The description reinforces this by specifying the HTTP endpoint and authorization class. While it doesn't explicitly state 'retrieve costs per agent model', the purpose is sufficiently clear from the naming and context.
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 on when to use this tool versus sibling cost reports (by_agent, by_provider, etc.). The description merely states the endpoint without explaining the grouping criteria or use cases. The agent is left to infer 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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's mention of 'GET' operation and authorization class adds some context but does not significantly expand behavioral understanding. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
At two sentences, it's brief but the first sentence repeats the title verbatim. It could be more efficient by merging the title and operation details.
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 large number of sibling cost report tools and the presence of an output schema (which is not described), the description lacks context about what the output contains, any filtering capabilities, or how finance-by-biller differs from other breakdowns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no information about the required companyId parameter (e.g., format, example, or meaning). This is a critical omission.
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 title and first sentence clearly indicate a cost report grouped by biller. The HTTP path reinforces this. However, it doesn't explicitly differentiate from sibling cost tools like costs_by_agent or costs_by_provider, which share the same company context.
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 on when to use this tool versus alternative cost report tools (e.g., costs_by_agent, costs_by_provider). The description only states the HTTP method and authorization class, not usage 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 indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds the authorization class and HTTP method, but does not disclose potential pagination, limits, or other behaviors beyond what annotations imply. The value added is marginal.
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 very short (two sentences) and front-loads the core purpose. It includes relevant technical details without fluff. Minor improvement could be to structure the parameter information separately.
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 simplicity (one parameter, output schema exists), the description is minimal but leaves gaps: no parameter description, no usage context, and no differentiation from siblings. The 0% schema coverage makes the description insufficient for complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not describe the 'companyId' parameter at all. It only reiterates the path structure. The agent receives no information about what the parameter represents, its format, or constraints.
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 title and description clearly state the tool lists company feedback traces. The technical details (HTTP method, path) add precision, but it does not explicitly differentiate from similar tools like pc_get_issues_by_id_feedback_traces or pc_get_feedback_traces_by_trace_id.
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 mentions authorization class 'board_or_agent', which is a permission guideline, but it provides no guidance on when to use this tool versus its siblings (e.g., when to list feedback traces for a company vs. for an issue). No exclusions or alternative suggestions 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 provide readOnlyHint and idempotentHint. The description adds the authorization class and endpoint, adding some behavioral context. However, it does not mention pagination, result limits, or data freshness beyond openWorldHint.
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 short (two sentences) but includes redundant 'Paperclip operation:' detail that may be noise for an AI agent. The auth class is useful, but the structure is minimal.
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 lacks details about output structure (though output schema exists), definition of 'join requests,' and cross-references to sibling tools for managing them. The agent may not fully understand the tool's role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds no explanation of the companyId parameter (e.g., its meaning or required format). The agent receives no parameter guidance beyond the schema's type and required flag.
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 'List company join requests' which clearly identifies the action and resource. However, it does not differentiate from sibling tools like pc_post_companies_by_company_id_join_requests, which are write operations.
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 on when to use this tool versus alternatives (e.g., other join request tools). The description mentions 'Authorization class: board' but does not explain context 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?
Annotations already declare readOnlyHint: true, idempotentHint: true, and destructiveHint: false. The description adds only the authorization class 'board_or_agent', which is a useful but minimal addition. No other behavioral details are disclosed.
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 includes a redundant first sentence that repeats the title. The endpoint and authorization class are useful, but overall it could be more efficient by combining sentences.
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 two undocumented parameters and a nested input schema, the description fails to provide essential context about the report's scope or the effect of parameters. The output schema exists but is not referenced. Auth info is the only addition beyond the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the purpose or format of the 'weeks' or 'threshold' parameters. The agent must infer their meaning from context or guess, which is inadequate for a tool with an output schema available.
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 verb 'Get' and the resource 'recovery observability report', and provides the API endpoint. However, it does not detail what the report contains, which could confuse an agent about the specific data returned.
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 on when to use this tool versus alternatives, such as pc_get_issues_by_id_recovery_actions. The authorization class is mentioned but not elaborated. No when-not-to-use context 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?
The description states it is a GET operation with 'Authorization class: board_or_agent', which is consistent with the annotations (readOnlyHint=true, destructiveHint=false, idempotentHint=true). It does not contradict annotations but adds minimal behavioral context beyond what annotations already indicate.
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 very concise, consisting of two short sentences with no redundant content. However, it could include more useful information without becoming verbose, so it scores well but not perfectly.
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 lacks important context such as the relationship to search operations, what the output contains (despite an output schema being present), and prerequisites. This leaves significant gaps for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention the `companyId` parameter at all. The parameter name is self-explanatory, but the description adds no meaning or constraints, leaving the agent to infer the parameter's role from the tool name alone.
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 restates the title 'Extract company search matches' without elaborating on what exactly 'search matches' are or how this differs from sibling tools like `pc_get_companies_by_company_id_search`. The purpose is implied but not clearly specified, and no distinction from alternatives is provided.
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 on when to use this tool versus alternatives such as `pc_get_companies_by_company_id_search` or `pc_get_companies_by_company_id`. The description only provides the HTTP endpoint and authorization class, leaving the agent without context for invocation.
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, signaling a safe read operation. The description adds the HTTP method and authorization class (board_or_agent), which provides useful but minimal behavioral context beyond what annotations offer.
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 very brief: one line for the action and one line for the HTTP method and auth class. It is concise but slightly technical. Every sentence earns its place, though the second line could be more user-friendly.
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, the description lacks parameter explanations and usage guidance. For a simple list tool with one parameter and many siblings, the description is incomplete. It only barely covers the minimum.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning the description must explain the parameters. However, it does not describe the required 'companyId' parameter (nested under 'path'). The agent receives no cues about what to provide or the parameter's purpose.
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 title 'List secret providers' clearly indicates a listing operation. The description reinforces the verb+resource pattern. While the resource 'secret providers' is not further defined, it is distinct from siblings like health checks or config retrieval 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 such as pc_get_companies_by_company_id_secrets or pc_get_secret_provider_configs_by_id. The agent is left to infer context from the resource 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?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds the HTTP method (GET) and authorization class ('board_or_agent'), providing some transparency beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short, but it includes technical details (Paperclip operation, authorization) that are useful. However, it lacks structure (e.g., parameter descriptions) that would aid agent comprehension. It is not overly verbose but could be better organized.
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, the description omits details about what versions are or what the response contains. Parameter descriptions are missing. Annotations cover safety, but the description fails to provide complete context for an agent to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description provides no explanation of the path parameters (companyId, skillId). The agent must rely solely on parameter names, which is insufficient for a tool with nested objects and required fields.
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 title 'List skill versions' and description clearly indicate the tool lists versions of a skill for a given company and skill. The resource is specific, but there is no explicit differentiation from sibling tools like getting skill details or creating versions.
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 on when to use this tool versus alternatives (e.g., get skill details, create version). No exclusions or prerequisites mentioned, leaving the agent to infer 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?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description adds little beyond the HTTP method and authorization class. Important behavioral details like pagination, ordering, or filtering are missing.
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, front-loading the purpose in the first sentence. No unnecessary words 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?
Given the complexity of the domain and the existence of an output schema, the description fails to provide context about what the returned list contains or how to interpret results. It is insufficient for an agent to fully understand the tool's role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Parameters have 0% schema description coverage, and the description does not elaborate on the only parameter (companyId). No explanation of its format, meaning, or constraints beyond what the schema 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 clearly states 'List skill test-run templates', which is a specific verb-resource pair. It distinguishes from sibling tools like pc_post/patch/delete_companies_by_company_id_skill_test_run_templates. However, it does not clarify what a 'skill test-run template' is, leaving some 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 on when to use this tool vs alternatives. For example, pc_get_companies_by_company_id_skills_by_skill_id_test_runs might also list test runs but is different. No when-to-use or when-not-to-use advice 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. The description adds the authorization class 'board_or_agent', which is useful but does not significantly expand on behavioral traits beyond what annotations provide. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and to the point, with no wasted words. However, it could be improved by adding parameter details 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?
Despite having an output schema, the description fails to explain what the timeline contains or how to interpret it. With 9 parameters and no parameter descriptions, the tool is incomplete for an agent to use effectively. Annotations cover safety but not usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it provides no information about the required or optional parameters (companyId, to, from, limit, etc.). The agent has no clue what these parameters represent or how to use them.
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 retrieves a company's work timeline with a specific verb and resource. However, it does not differentiate from sibling tools like pc_get_companies_by_company_id, which also fetch company data, so it loses a point for lacking 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?
No guidance is provided on when to use this tool versus alternatives. There is no mention of when-not-to-use or any prerequisites, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, non-destructive behavior. The description adds the HTTP method (GET) and authorization class ('board'), which is useful 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two lines), but the first line simply repeats the title from annotations, making it redundant. The second line adds value with endpoint and auth class. It is concise but not optimally structured (wasted repetition).
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 lacks information about the required 'companyId' parameter and what constitutes a valid value. Although an output schema exists, the agent has no context on pagination, ordering, or the response shape. The minimal description leaves gaps for this simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the schema provides no parameter descriptions. The description fails to compensate: it does not explain the 'companyId' parameter or the nested 'path' object. The agent receives no guidance on parameter meaning or format.
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 'List tool app gallery entries' with a specific verb and resource. The endpoint path reinforces this. However, it does not explicitly differentiate from other list tools like pc_get_companies or pc_get_skills_catalog, though the resource name 'tool app gallery entries' is 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?
The description provides no guidance on when to use this tool versus alternatives. No context about prerequisites, scenarios, or exclusions is given. The agent is left to infer usage from the name and endpoint 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?
Description adds the HTTP method (GET) and authorization class, which supplements annotations (readOnlyHint, destructiveHint). However, it does not disclose behavior like pagination or error handling. Annotations already cover safety profile.
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?
Very short (two sentences), but the first sentence is redundant with the title. No wasted words, but also lacking substance. Could be improved with parameter details.
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 simplicity (1 parameter), the description is incomplete. It does not explain the output or how to use it, though an output schema exists. The tool's purpose remains vague.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain the parameter 'companyId' but fails to do so. The parameter is entirely undocumented, leaving the agent without guidance.
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 'Get company user directory', which specifies the action (get) and resource (user directory). It distinguishes from sibling tools like pc_get_companies by specifying the directory, but lacks detail on what the directory contains.
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 on when to use this tool versus alternatives. No context about prerequisites, exclusions, or typical use cases.
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, destructiveHint=false. The description adds the HTTP method (GET) and authorization class, but does not describe any behavioral traits beyond what annotations imply. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence repeats the title, which is redundant but minor. The structure is clear and 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?
Despite good annotations, the description lacks essential context about what 'coverage' entails and when to use this tool. Parameters are undocumented, and the output schema is not described. The agent has insufficient information to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only mentions the path structure in the HTTP line. There is no explanation of companyId or definitionId, their meaning, or how to obtain them. The output schema exists but remains unseen.
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 states the verb 'Get' and resource 'user secret definition coverage', but does not explain what 'coverage' means or how it differs from related tools like pc_get_companies_by_company_id_user_secret_definitions or pc_get_companies_by_company_id_me_user_secrets. The HTTP path is given but no semantic 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?
No guidance on when to use this tool versus alternatives. There are many secret-related sibling tools, but the description does not provide any selection criteria, prerequisites, or context for invocation.
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 adds the HTTP method, endpoint path, and authorization class, which are useful beyond the annotations. However, it does not explain behavior when no template exists or error conditions. Annotations already indicate read-only and non-destructive nature, so the description adds some but limited value.
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 (two sentences) and front-loaded with the main purpose. It is concise, though the second sentence is a technical detail that could be integrated. No redundant text.
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 an output schema, the description does not need to fully document return values, but it fails to explain the input parameters or provide context on the setup status and template. It lacks completeness for a tool with zero schema description coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the meaning or format of any parameter (environmentId, companyId). It relies entirely on the schema, which lacks descriptions. This severely hinders correct parameter usage.
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 it retrieves the active custom image template and setup status for an environment, providing a specific verb and resource. However, it does not differentiate from other custom image tools (e.g., POST or DELETE), which slightly reduces 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?
No guidance is given on when to use this tool versus other custom image tools or alternatives. The description only states the action, not the context 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. The description adds the REST endpoint and authorization class, providing useful but limited behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences. The first sentence repeats the title, but the second provides additional technical detail. It is short and to the point.
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 requires understanding of what a 'feedback trace bundle' is, the description fails to provide necessary context. While an output schema exists, the description does not clarify the tool's role or when it should be invoked.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description must compensate but does not. It only mentions traceId in the URL but provides no semantics about its meaning or constraints.
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+resource ('Get a feedback trace bundle'), clearly indicating the action. However, it does not differentiate from its sibling tool 'pc_get_feedback_traces_by_trace_id', which likely retrieves a single trace versus a bundle.
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 pc_get_feedback_traces_by_trace_id. It lacks any context about appropriate use cases or when to avoid it.
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 readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds authorization class (board_or_agent), which is useful. No contradictions. However, it does not disclose other behavioral traits like pagination or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: one for purpose, one for technical details (HTTP method, path, auth). No fluff, front-loaded with purpose. Concise but still includes relevant implementation 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?
Even with an output schema, the description lacks context about what workspace operations are and does not explain the single parameter. For a list operation with one parameter, it should provide more guidance on usage and behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not describe the required 'runId' parameter. The description adds no meaning beyond what the schema provides. The parameter name is self-explanatory, but the description should at least mention it.
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 it lists workspace operations for a run. The title and name clarify it's for heartbeat runs, distinguishing it from similar tools like pc_get_execution_workspaces_by_id_workspace_operations. However, it could be more specific about what 'workspace operations' are.
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 on when to use or not use this tool. The name implies it's for heartbeat runs, but there is no mention of alternatives or context. The description only provides technical details, not usage advice.
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 provide readOnlyHint, idempotentHint, and non-destructive nature. The description adds that it is a GET operation and public authorization, but does not disclose potential error cases or response format. Does not contradict annotations; annotation_contradiction is false.
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 very concise (two sentences) and front-loads the purpose. It could be slightly longer to cover parameters, but for what it contains, it is efficient and avoids 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?
Given the low schema coverage, the description does not compensate by explaining the token parameter. It also does not clarify whether the logo is for the invite's company or another entity. The presence of an output schema reduces the need to explain return values, but overall completeness is lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'token' parameter at all. The parameter is only defined in the schema as a required string with no further context, leaving the agent unclear on what token is expected.
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 title and description clearly state the action (Get) and resource (company logo for an invite). However, it does not explicitly differentiate from sibling invite tools like pc_get_invites_by_token, which also retrieves invite data, but the purpose is sufficiently 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 mentions 'Authorization class: public', indicating it can be used by anyone. But there is no guidance on when to use this tool versus alternatives (e.g., other invite tools), nor any prerequisite or context for 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`, which convey safety and idempotency. The description adds the HTTP method and authorization class, but no additional behavioral traits beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short—two sentences covering purpose and endpoint details. It is concise but could be more informative without adding much length.
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, the description lacks essential context: it does not clarify what a 'skills index' contains, how to use the parameter, or when to invoke this tool. The missing parameter semantics and usage guidance make it incomplete for an agent to reliably select and use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one required parameter `token` with no description. The description does not explain the parameter's purpose, format, or how to obtain it. With 0% schema coverage, the description fails to compensate, leaving the parameter's semantics undefined.
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 'Get skills index for an invite,' clearly indicating the verb and resource. However, it does not explain what 'skills index' means or how this tool differs from other invite-related siblings like `pc_get_invites_by_token` or `pc_get_invites_by_token_skills_by_skill_name`, leaving some 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 on when to use this tool versus alternatives. The sibling list includes several invite-token tools, but the description offers no context, exclusions, or selection criteria.
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, destructiveHint=false. The description adds HTTP method and authorization class but does not disclose behavioral traits like pagination, filtering, or what happens if unauthorized. It adds minimal value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (two sentences). It front-loads the purpose and adds implementation details. However, it sacrifices completeness 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 list endpoint, the description lacks information about output format, pagination, or sorting. Although an output schema exists, the description should provide context on what the tool returns (e.g., list of approval objects). It feels 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?
Schema coverage is 0% and the description does not explain the only parameter 'path.id'. While the tool name implies it's an issue ID, the description should explicitly state that 'id' refers to the issue ID. It adds no meaning beyond what the name suggests.
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 'List issue approvals', which is a specific verb+resource. The title matches. However, it does not explicitly differentiate from sibling tools like pc_get_issues_by_id_comments or pc_get_approvals_by_id, though the naming makes it fairly 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?
No guidance on when to use this tool versus alternatives (e.g., pc_get_companies_by_company_id_approvals, pc_get_approvals_by_id). It mentions authorization class but 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?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds the HTTP operation and authentication class, but does not disclose any behavioral traits beyond what annotations provide. The authorization class is a useful addition, but overall transparency is adequate given annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short, consisting of two sentences. The first sentence captures the core purpose. The second sentence provides technical details (operation and auth). It is concise but could be more front-loaded with essential information.
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 presence of an output schema, the description does not need to cover return values. However, it lacks explanation of what blocker diagnostics are, how the parameter is used, and how this tool relates to sibling diagnostics tools. The single parameter's semantics are missing, making the description incomplete for effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions are present. The description does not explain the 'path.id' parameter at all, leaving the agent to infer that it is an issue ID. This is a significant gap for a tool with a single required parameter.
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 'Get blocker diagnostics for an issue', specifying the resource (blocker diagnostics) and the action (get). However, it does not differentiate from sibling diagnostics tools like pc_get_issues_by_id_diagnostics_wakes or pc_get_issues_by_id_diagnostics_subtree, which have similar names.
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 includes the HTTP method and authorization class, but no context about use cases or scenarios where blocker diagnostics are appropriate.
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. The description adds the HTTP method and authorization, but does not disclose any additional behavioral traits 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief with two sentences, but the first sentence repeats the title. It is not front-loaded with new information beyond the title.
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, the description lacks parameter explanations. For a tool with one parameter and no schema description coverage, the description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no explanation of the 'path' parameter or its inner 'id' field. With 0% schema description coverage, the description must compensate but fails to add any parameter 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 the tool retrieves an external object status summary for a specific issue. It also includes the HTTP method and path. However, it does not differentiate this tool from sibling tools like pc_get_issues_by_id_external_objects.
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 on when to use this tool versus alternatives. The only hint is the authorization class, which is not sufficient for 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?
Annotations already provide readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds only the HTTP method and authorization class, which are not behavioral traits covered by annotations. No additional behavioral context 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two lines) but lacks structure. The first line repeats the title, and the second line adds operational details. It could be more concise and front-loaded with essential information.
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 existence of an output schema, the return format may be understood, but the description does not explain what feedback traces are, their significance, or how this tool fits into the broader issue workflow. The parameter is not described, making the tool less complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is one required parameter (path.id) with no description in the input schema (0% schema coverage). The description does not mention or explain the parameter at all, so the agent has no guidance on how to supply the issue ID.
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 verb 'List' and the resource 'issue feedback traces', making the basic purpose clear. However, it does not differentiate from sibling tools like pc_get_issues_by_id_feedback_votes or pc_get_feedback_traces_by_trace_id, which are similar.
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 includes the HTTP method and authorization class, which provides some guidance on when the tool can be used (requires board_or_agent auth). However, it does not mention when to prefer this over alternatives or any specific 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 readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, covering safety and idempotency. The description adds the HTTP method (GET) and authorization class (board_or_agent), which are useful but not behavioral traits beyond what annotations provide. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (two lines: title and technical details). While concise, it omits critical information about parameters and usage. The structure is minimal: a title line followed by implementation details. It is front-loaded with the purpose, but lacks depth. Every word earns its place, but the result is under-specification rather than optimal 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?
Despite annotations covering safety (readOnly, idempotent), the description fails to explain what a 'tree hold' is or when this operation is relevant. The output schema exists but is not included in the description, so the agent doesn't know what the response contains. Given the simplicity of the tool (2 path params), the description should at least clarify the parameters and the resource concept.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has two parameters (id, holdId) with schema description coverage of 0%. The description does not explain what these parameters represent or how they are used. It merely repeats the tool name. With no param descriptions in schema or prose, the agent lacks essential context to correctly fill in the path 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 states 'Get an issue tree hold' which matches the tool name and title. It clearly identifies the verb (Get) and the resource (issue tree hold). The sibling tools include pc_get_issues_by_id_tree_holds for listing, so this tool's purpose as a get-by-id operation is distinguishable. However, it does not explicitly state that it retrieves a single hold by ID, which is evident from the parameter schema but not clarified in text.
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 pc_get_issues_by_id_tree_holds (list) or pc_post_issues_by_id_tree_holds_by_hold_id_release (release). There is no mention of prerequisites, context, or exclusion criteria. The only extra information is the authorization class, which helps but doesn't guide usage decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the HTTP method (GET) and authorization class, which provides some additional context 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) and front-loads the purpose. However, it is under-specified; more meaningful guidance could be included without sacrificing 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 the tool's single parameter, existing annotations, and output schema, the description lacks context about what an 'active run' is and how this tool fits among related run tools. It does not explain the return value or typical use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description offers no details about the sole parameter `issueId` (e.g., format, constraints, or purpose). The description fails to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get active run for an issue', which is a specific verb and resource. However, it does not differentiate from sibling tools like pc_get_issues_by_id_runs that also retrieve run data for an issue, leaving ambiguity about what 'active run' means versus other runs.
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., pc_get_issues_by_id_runs for non-active runs). There are no when-to-use or when-not-to-use instructions.
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 provide safety profile (read-only, idempotent, non-destructive). The description adds minimal behavioral context (endpoint, authorization class) but does not disclose additional traits like filtering behavior or return format beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two sentences), but the second sentence (endpoint and authorization) adds limited value and could be omitted. It is adequately sized but not optimally 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?
Despite having an output schema (so return values are covered), the description omits essential context: what constitutes a file resource, pagination details, and the meaning of query parameters. This is insufficient for a tool with many parameters and zero schema descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no parameter descriptions). The description does not explain any parameters, not even the required issueId or the optional query parameters. This severely hampers correct invocation.
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 title and description clearly state the tool lists workspace files for an issue, with a specific verb and resource. It is distinct from many siblings but does not differentiate among similar issue-related file tools like attachments or documents.
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 on when to use this tool versus alternatives (e.g., get documents, get attachments). The description lacks context about suitable scenarios or exclusions, making it hard for an AI to choose correctly among many sibling 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 provide readOnlyHint, idempotentHint, and openWorldHint, so the description's addition of 'Authorization class: board_or_agent' adds some value. However, it does not disclose other behaviors like response format or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short with two sentences, but the first sentence repeats the title redundantly. The second sentence adds useful technical details. It is appropriately sized for a simple 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?
For a read-only tool with one parameter, the description omits crucial parameter documentation and does not leverage the existing output schema. The agent lacks sufficient context to reliably select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the parameter 'adapterType' lacks any meaning beyond being a string. The description does not specify valid values, format, or examples, leaving the agent without guidance.
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 it retrieves agent configuration for a specific adapter type, which is distinct from the generic 'pc_get_llms_agent_configuration_txt' sibling. However, it does not explicitly differentiate from other similar 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 on when to use this tool versus alternatives. The description lacks context about prerequisites or usage scenarios, relying solely on the parameter to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by mentioning 'Authorization class: board'. However, it fails to describe the streaming behavior (e.g., persistent connection, event flow) beyond the 'SSE' acronym, which is not explained.
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 only two sentences and directly states the purpose and endpoint. It is concise, but could be improved by front-loading the streaming nature and parameter roles.
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 annotations and an output schema (not shown), the description is incomplete. It fails to explain how to use the tool (e.g., handling SSE events), differentiate it from other plugin tools, or define key parameters. The agent is left with significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter (path with pluginId and channel) with 0% description coverage. The description does not explain either parameter, leaving agents to infer their meaning from the tool name. This is insufficient for correct invocation.
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 'Subscribe to a plugin bridge SSE stream' and provides the endpoint, which distinguishes it from sibling tools like pc_post_plugins_by_plugin_id_bridge_data and pc_post_plugins_by_plugin_id_bridge_action. However, it does not explain what SSE means or what subscribing entails, leaving some 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 on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or scenarios where other bridge tools would be more appropriate. The agent must infer usage from the tool name and title.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, providing safety and idempotency info. The description adds the HTTP method and authorization class, which offers some extra detail but does not reveal significant behavioral traits beyond what annotations cover.
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 very concise, consisting of two short sentences. It is front-loaded with the purpose. However, it might be too brief given the lack of param info.
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 tool is simple and has output schema and annotations, the description lacks crucial context about usage, parameter meanings, and how it fits with sibling tools. The 0% schema coverage makes the incomplete description more problematic.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions in the schema. The tool description does not add any information about the parameters (pluginId, companyId). With zero coverage and no description, the agent cannot infer semantics of required inputs.
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 'List plugin local folders', which is a specific verb+resource combination. The title matches. While it does not explicitly distinguish from siblings, the purpose 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention any context, prerequisites, or exclusions. The sibling list contains many similar tools, but no differentiation 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, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds the HTTP method and endpoint, and 'Authorization class: board' for permissions. However, it does not disclose error handling, rate limits, or behavior for invalid inputs, which is acceptable given the annotations lower the burden.
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) and front-loaded with the purpose. However, it sacrifices completeness for brevity, omitting important details about parameters and output. It could be more structured but remains acceptable in length.
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 (not shown), the description does not explain what 'dashboard data' contains, leaving the agent uncertain about the return value. For a simple tool with one parameter, more context about the output is needed to make informed decisions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no descriptions in the input schema. The description does not add any meaning to the pluginId parameter beyond its presence in the endpoint URL. No format, constraints, or examples are provided. This is a significant gap.
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 'Get plugin dashboard data' and the resource 'plugin dashboard'. It includes the HTTP method and endpoint, which aligns with the title. However, it does not differentiate from similar plugin retrieval tools like pc_get_plugins_by_plugin_id or pc_get_plugins_by_plugin_id_health, lacking specific scope of what 'dashboard data' includes.
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 specify prerequisites, context, or when not to use it. The only extra information is 'Authorization class: board', which hints at access requirements but not usage 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 provide readOnlyHint, idempotentHint, and destructiveHint false. The description adds 'Authorization class: board', which informs about authentication requirements. This adds some value beyond annotations, but the description does not disclose any additional behavioral traits like rate limits or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences), concise, and front-loaded with the purpose. However, the second sentence could be more structured, but overall it is appropriately sized without extra fluff.
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 presence of an output schema, the description does not need to explain return values. However, it lacks context about what a tool connection is, how it fits into the system, or any relationships. The description is minimal and does not fill in gaps beyond the structured fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fails to explain any parameters. The 'connectionId' parameter is only defined in the schema; the description does not mention it or provide any semantics. This is a significant gap.
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 'Get a tool connection', indicating the action (Get) and resource (tool connection). It distinguishes from sibling tools like patch or delete, but the differentiation is implicit. The technical details (Paperclip operation, Authorization class) add context but are not essential for purpose 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 context on prerequisites or exclusions. It merely repeats the endpoint and authorization class, offering no usage recommendations.
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 destructiveHint=true and readOnlyHint=false. The description adds that it is a PATCH operation to enable/disable, which is useful but does not disclose further behavioral details (e.g., consequences of disabling, reversibility). With annotations carrying some burden, this is adequate but minimal.
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 only two sentences, front-loaded with the purpose. No unnecessary words. However, it is too brief to cover essential information, but conciseness is not about completeness.
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 simple 2-parameter tool with an output schema and annotations, the description is incomplete. It lacks parameter explanations, usage context, and any details about the output. The agent cannot fully understand how to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description does not mention any parameter. It fails to explain what the 'disabled' boolean means (true=disable? false=enable?) or what the 'type' path parameter represents. The description adds no value beyond the schema structure.
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?
Description clearly states 'Enable or disable an adapter' – a specific verb and resource. It distinguishes itself from sibling adapter tools like pc_patch_adapters_by_type_override or pc_post_adapters_by_type_reload, though it does not explicitly differentiate.
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 the HTTP method and authorization class, but gives no guidance on when to use this tool versus alternatives (e.g., override, reinstall). The agent receives no context for choosing this 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 indicate non-readOnly and non-destructive behavior. The description adds authorization class ('board_or_agent'), which is helpful for understanding access requirements. However, it does not explain update semantics (e.g., whether this replaces the bundle or merges), potential side effects, or error conditions. With annotations covering some aspects, the description adds moderate value.
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, but it omits critical information. It front-loads the purpose but fails to provide necessary details. Structure is straightforward but sacrifices completeness 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 the tool modifies a complex resource with a nested schema and an output schema exists, the description should provide context on return values, prerequisites, and relationship to other tools. It does none of these. The 0% parameter coverage further exacerbates the lack of completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, placing full burden on the description to explain parameters. The description mentions no parameters, leaving the agent to interpret 'body' properties (mode, rootPath, entryFile, clearLegacyPromptTemplate) and 'path.id' solely from their names. This is insufficient for correct parameter selection and invocation.
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 title and description clearly state 'Update agent instructions bundle', indicating the primary action. However, the description does not differentiate this tool from similar sibling tools like pc_patch_agents_by_id_instructions_path, which also modifies instructions. The purpose is clear but lacks distinguishing context.
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 prerequisites, when to use this over other agent update tools, or any specific use cases. The agent must infer usage from the name and schema 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?
Annotations provide basic behavioral hints (readOnlyHint=false). Description adds authorization class 'board_or_agent', which is useful but minimal. No further behavioral context (e.g., side effects, rate limits) is disclosed.
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. It avoids redundancy but underutilizes the space; could include more critical context without hurting conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with nested objects and complex schema, the description lacks any explanation of the body structure, required fields, or behavior. It fails to provide sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameter semantics. Not even the required 'body' or 'path' fields are described, forcing reliance solely on the input 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 title and description clearly state 'Update agent permissions', identifying the specific action and resource. However, no differentiation from sibling tools like pc_patch_agents_by_id is provided.
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 on when to use this tool versus alternatives (e.g., other agent update tools). Lacks context for 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the HTTP method (PATCH) and authorization class (board_or_agent) beyond the annotations, which indicate mutability (readOnlyHint=false) but no destructiveness. However, it does not disclose behavioral details like whether the update is incremental or replaces the entire budget, or any side effects (e.g., budget enforcement). The annotation set does not provide clear behavioral guidance, so the description carries some burden but only partially fulfills it.
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 concise, with two sentences that convey the operation and authorization. It is front-loaded with the primary purpose. While not verbose, it could be slightly more structured (e.g., separate sections), but overall it is efficient and easy to parse.
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 (2 required parameters, no schema descriptions, presence of output schema), the description lacks essential context. It does not explain the semantics of 'budget' (e.g., monthly budget for the whole company or per agent?), whether the update is additive or full replacement, or any constraints beyond the schema. The output schema exists but is not detailed, so the description should compensate but fails to do so.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions (0% coverage), and the description does not mention any parameter details. Parameters like budgetMonthlyCents (integer, min 0) and companyId (string) are left entirely to the schema, which lacks explanations. The description adds zero value beyond the raw schema structure.
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 title 'Update company budget' and description clearly state the action (update) and resource (company budget), with the HTTP method PATCH adding specificity. While it doesn't explicitly differentiate from sibling budget tools like get budgets overview or agent budget updates, the name and purpose are sufficiently clear for an agent to understand the tool's core function.
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 vs alternatives (e.g., other budget tools, company update tools). It mentions an authorization class but does not contextualize usage scenarios, prerequisites, or when not to use it. This is a significant gap for an agent deciding between 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 indicate readOnlyHint=false (modifies data), destructiveHint=false, and idempotentHint=false. The description adds the authorization class 'board_or_agent,' which provides useful context beyond annotations. However, it does not disclose any additional behavioral traits, such as what happens on success or if the folder does not exist.
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 very concise—two sentences—and front-loaded with the core purpose. It is efficient but could benefit from structured information without becoming verbose.
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 that an output schema exists, the description does not mention the return format. For a mutation tool, it should indicate what is returned (e.g., the updated folder). Combined with low parameter semantics and no usage guidance, the description is incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of any parameters. The agent must rely solely on property names and types for the body fields (name, slug, color, position) and path parameters (companyId, folderId). This is inadequate for correct tool invocation.
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 'Update a folder,' which clearly indicates the verb and resource. This is a PATCH operation that modifies an existing folder's properties. However, it does not differentiate from sibling folder tools like create or delete, lacking explicit context about what aspects of the folder can be updated.
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 (e.g., creating a new folder or deleting one). It does not mention prerequisites such as the existence of the folder or company, nor any conditions that should trigger this 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 a write operation (readOnlyHint=false) and non-destructive behavior (destructiveHint=false). The description adds the HTTP method (PATCH) and authorization class, which is useful but not enough to describe side effects or idempotency. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with no wasted words. However, it is overly brief and omits necessary details, making it less helpful than a slightly longer, more informative description.
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 lacks context for an update operation: it does not mention that this is a partial update (PATCH), what happens if fields are omitted, or the required IDs. Despite having an output schema and sibling tools, the description fails to provide sufficient context for safe usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameters. The agent must rely solely on schema field names (e.g., name, content, companyId) without any context about their semantics or constraints.
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 'Update a skill test input' and provides the API endpoint, making the tool's purpose evident. However, it does not differentiate this update tool from sibling create or get tools, missing explicit context for when to use update versus create.
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 POST (create) or GET (retrieve). The agent is left to infer usage from the tool name alone, which is insufficient.
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, destructiveHint=false, and idempotentHint=false, so the description's 'Update' is consistent. The description adds the authorization class 'board', which is a useful behavioral detail. However, it does not disclose other traits like whether the update is partial or full, or any side effects beyond what annotations imply.
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 (two lines), front-loaded with the purpose, and contains no fluff. However, it sacrifices necessary detail, making it feel incomplete rather than elegantly 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's complexity (a PATCH operation on a rich policy resource with many optional fields), the description is insufficient. It fails to specify what fields can be updated, the effect of changes, or how it interacts with other policy tools. The presence of an output schema partially compensates, but the description lacks essential context for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description must explain parameters, but it does not. The body parameter has many nested fields (name, config, enabled, priority, etc.), and the description offers no explanation of their meaning or usage, leaving the agent to rely solely on 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 'Update a tool policy', indicating the verb (update) and resource (tool policy). However, it does not differentiate from sibling tools like POST (create) or DELETE (delete), so it misses the opportunity to clarify that this is a partial update via PATCH.
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 includes the HTTP method and endpoint, but this is not usage guidance. There is no mention of when to use PATCH vs POST (create) 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the authorization class 'board_or_agent' and confirms it is a PATCH operation, which aligns with annotations (readOnlyHint=false, destructiveHint=false). However, it does not disclose any additional behavioral traits such as idempotency, side effects, or error conditions beyond what annotations already indicate.
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 concise with two sentences: the first states the purpose, the second provides operational context (HTTP method and auth). It is front-loaded and avoids unnecessary text, but could include parameter details without becoming verbose.
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?
While an output schema exists (so return values are documented elsewhere), the description lacks context about what 'decision training' is and how this update fits into a workflow. With no parameter descriptions and minimal usage guidance, the agent may struggle to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions exist in the schema. The tool description does not explain the 'body.notes' or 'path.id' parameters at all, leaving the agent without guidance on their meaning or format. This is a significant gap.
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 'Update decision training notes', which specifies a verb ('Update') and a resource ('decision training notes'). This is specific and distinct from sibling tools like get or delete operations for the same resource, though it could further clarify that only the 'notes' field is updated.
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 mentions the HTTP method and authorization class, but does not indicate when to use this tool versus alternatives such as pc_get_decision_training_by_id or pc_post_companies_by_company_id_decision_training. No guidance on prerequisites or context is provided.
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 readOnlyHint=false and destructiveHint=false, so the description adds minimal behavioral context beyond 'Authorization class: board_or_agent'. It does not explain the partial update semantics (PATCH) or what fields are updated.
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 only two sentences long, which is efficient but too brief to cover necessary details. It wastes no words but lacks critical information about parameters and behavior.
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 many optional fields in the body and no output schema provided, the description is incomplete. It fails to explain what each body parameter does, any constraints, or the effect of a PATCH update. Only the authorization class is useful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description does not explain any of the parameters. The body object has many fields (name, config, driver, status, envVars, etc.) but the description provides no context about their meaning or 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 clearly states 'Update an environment' with the specific HTTP verb PATCH, distinguishing this tool from create (POST), read (GET), and delete (DELETE) environment tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 like pc_get_environments_by_id or pc_post_companies_by_company_id_environments. It only repeats the title and adds operation 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 indicate non-readonly and non-destructive behavior. Description adds the API path and authorization class, which are not in annotations. However, it does not disclose other behavioral traits like immediate effect or rollback possibilities.
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 concise (two sentences) and front-loaded with the purpose. However, it mixes internal metadata (operation, auth class) which could be in structured fields.
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 an update tool with one required parameter and nested object, the description is minimal. It does not explain the effect of the update, return value, or provide examples, despite having an output schema and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of the 'body' parameter or the 'defaultEnvironmentId' property. The output schema exists but is not referenced. This is a critical gap.
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 'Update instance settings' and includes the specific API path, distinguishing it from sibling tools like pc_get_instance_settings or pc_patch_instance_settings_general. However, it could explicitly differentiate itself from these siblings.
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 on when to use this tool versus alternatives. There is no context about prerequisites, use cases, or situations where this tool should be preferred.
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 provide basic traits (readOnlyHint=false, destructiveHint=false) but add little beyond that. The description mentions the HTTP method and authorization class, which adds some value but does not disclose partial update behavior or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very brief (two sentences), but lacks critical information about parameters and usage. Conciseness is not helpful when it omits necessary 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 complexity of the input schema (many nested fields) and no output schema, the description is severely incomplete. It does not explain return values, required fields, or how to construct the body.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the body properties or the path parameter. The agent receives no guidance on what fields can be updated or their 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 the tool updates an issue, which is a specific verb+resource. However, it does not differentiate from sibling tools like pc_get_issues or pc_delete_issues, which also relate to issues.
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 on when to use this tool versus other issue-related tools (e.g., pc_post_issues or pc_patch_issues_by_id alternatives). No prerequisites or conditions 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 indicate this is a non-read-only, non-idempotent mutation. The description adds the authorization class ('board_or_agent'), which is useful, but does not disclose side effects, partial update behavior, or response details. With annotations already providing basic behavioral cues, the description adds moderate value.
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 short but lacks essential details. It is not verbose, but it sacrifices completeness for brevity. Every sentence serves a purpose, but more context is needed for a tool with many parameters.
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 (large input schema, many sibling tools), the description is insufficient. It does not explain what fields are updatable, that it is a partial update (PATCH), or any constraints. The output schema exists but the description adds no value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about the body or path parameters. Given the complex schema with many fields under 'body', the absence of any parameter guidance makes the tool difficult to use correctly.
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 'Update a routine', specifying the verb and resource. However, it does not distinguish this tool from its siblings like pc_get_routines_by_id or pc_post_companies_by_company_id_routines, missing an opportunity to differentiate.
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 lacks any guidance on when to use this tool versus alternatives. It does not mention prerequisites, when a routine can be updated, or contrast with create/delete operations.
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 mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds the HTTP method and authorization class, but does not elaborate on side effects, partial update behavior, or required permissions beyond 'board'. With annotations covering basic safety, a 3 is fair.
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 very concise (two sentences) and front-loaded with the core action. However, the second sentence with technical details could be integrated more naturally. It earns a 4 for efficiency.
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 that output schema exists and annotations are present, the description still lacks important context such as whether the update is partial or full, prerequisites (gateway must exist), and typical use cases. This makes it incomplete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not explain any parameters. The body requires a companyId, and path requires a gatewayId, but their semantics are not clarified. This is a significant gap.
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 resource ('named MCP gateway'), making the purpose clear. However, it does not distinguish this from sibling tools for creating or listing gateways, so a 4 is appropriate.
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 (e.g., creating a new gateway or deleting). There is no mention of prerequisites or context, leaving the agent to infer 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 provide readOnlyHint (false), destructiveHint (false), idempotentHint (false). Description adds authorization class 'board_or_agent' but does not disclose what reinstall actually does (e.g., does it reset state? require downtime?). No apparent 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: one tautological, one useful (HTTP method + auth class). Efficient but first sentence is redundant. No front-loading of key info beyond title.
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, the description is incomplete: no explanation of reinstall semantics, prerequisites, side effects, or relation to other adapter operations. For a potentially impactful operation, this is inadequate.
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?
Description does not mention parameters; schema provides description for 'body' but not for 'path.type'. Schema description coverage is 50%, and description adds no extra meaning. Parameters are left to the schema alone.
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 repeats the title 'Reinstall an adapter' verbatim, which is a tautology. It adds HTTP method and auth class but does not differentiate from sibling tools like 'reload' or 'delete+install'. Purpose is clear but minimal.
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 on when to use this tool vs. alternatives (e.g., reload, delete+install). No context on prerequisites, effects, or scenarios. Entirely lacking usage directives.
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 provide readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds the HTTP method (POST) and authorization class ('board_or_agent'), which provide some behavioral context beyond annotations. However, it does not explain potential side effects or what 'install' entails (e.g., downloading, enabling).
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 extremely short (two sentences) and avoids verbosity. However, it lacks substance—repeating the title and adding only endpoint/auth info. It is not well-structured to front-load critical usage details.
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 the complexity of the tool (nested input, output schema, many siblings), the description does not explain what the output represents, how to interpret results, or when this tool is needed. It leaves the agent without enough context to use it reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description does not mention any parameters. The input schema has one required parameter (body) with nested fields (packageName, version, isLocalPath), but the description provides no explanation of their semantics, purpose, or how they affect the installation. The description fails to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Install an adapter' with a specific verb and resource, matching the title. However, it does not differentiate from sibling tools like pc_post_adapters_by_type_reinstall, missing an opportunity to clarify the unique scope.
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., reinstall). There is no context about prerequisites, such as needing a package name, or when installation is appropriate. The description offers no 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 description notes the authorization class (board_or_agent), which is helpful, but fails to describe side effects (e.g., replacing current config, creating a new revision, state requirements). Annotations indicate destructiveHint=false, which may be misleading for a revert operation, but the description does not clarify.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) but under-specified, lacking essential operational details. It is not concise in a value-dense manner; rather, it omits critical information that the agent needs.
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 complexity of a rollback operation (mutating agent configuration, two parameters, output schema available but not described), the description is incomplete. It fails to explain the effect on the agent, the meaning of rolling back, or any constraints such as revision validity.
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 50%, yet the description does not explain any parameters. The optional 'body' parameter is poorly described in the schema, and the required 'path' object (containing id and revisionId) is not mentioned. The description adds no value beyond the schema's minimal details.
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 title and opening line clearly state 'Roll back to a config revision,' indicating a specific verb and resource. However, the description does not differentiate this tool from sibling tools that might modify agent configurations, such as pc_patch_agents_by_id, lacking explicit 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?
No guidance is provided on when to use this tool vs. alternatives, such as other agent modification tools. There is no mention of prerequisites, conditions for a valid rollback, or scenarios where rollback is inappropriate.
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 no behavioral context beyond what annotations already provide. Annotations indicate destructiveHint=true and readOnlyHint=false, but the description does not explain what pausing entails, what side effects occur, or any permissions needed. With annotations present, the bar is lower, but the description should still add value, which it does not.
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 extremely concise (one line), but it sacrifices necessary information. While conciseness is valued, it is under-specified for a mutating tool with two parameters and complex behavioral implications.
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 that this is a destructive operation with a required path parameter and an optional body, the description is incomplete. It does not explain what pausing does, how to provide the agent ID, or any expected outcomes. An output schema exists but is not leveraged in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%, and the description does not explain any parameter semantics. The path parameter 'id' is required but not described; the optional body is mentioned only as 'Optional JSON compatibility payload' in the schema, and the description ignores it entirely. The description adds no value over 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 title and description clearly state 'Pause an agent', which is a specific verb+resource. The operation is distinct among siblings; many other tools are about companies, issues, etc., so pausing an agent is clearly identifiable.
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. There is no mention of prerequisites, when pausing is appropriate, or any exclusions. The description is purely declarative.
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 destructiveHint=true. Description adds authorization class but does not explain behavioral implications of resetting a session (e.g., losing state, requiring re-login). Minimal additional value.
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?
Very short, but lacks structure. While it avoids fluff, it omits critical information that could be presented concisely.
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 fails to explain the purpose of 'taskKey' or what happens on reset. Incomplete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. Description does not explain the 'id' or 'taskKey' parameters, nor their purpose or constraints.
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 'Reset agent session' and identifies the HTTP operation and endpoint, distinguishing it from sibling tools like pause, resume, and terminate.
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 on when to use this tool versus alternatives (e.g., pause, terminate). Does not specify prerequisites or 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?
Annotations already declare destructiveHint=true, so the description minimally adds the authorization class ('board_or_agent'). It does not elaborate on side effects (e.g., irreversible termination, impact on ongoing tasks) or rate limits, which are critical for a destructive operation.
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 very short (two sentences), front-loading the core action. It avoids unnecessary words. However, it gains conciseness at the expense of substance, which limits its 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?
For a destructive action with annotations, the description lacks needed context: irreversibility, required permissions (beyond auth class), state dependencies, and return value. An output schema exists but no mention of what the response contains, leaving the user underinformed.
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 50% coverage (path.id is described, body is undocumented). The description adds no parameter details—it doesn't explain the required 'id' field or the purpose of the optional body. The schema itself is minimal, and the description fails to compensate.
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 terminates an agent and references the specific HTTP method and resource. It is straightforward but does not differentiate from sibling tools like pc_post_agents_by_id_pause or pc_delete_agents_by_id, which have distinct effects.
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 termination over pausing, resuming, or deleting an agent. It lacks context about prerequisites (e.g., agent must be running) or alternatives, leaving the agent to infer usage without 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 indicate readOnlyHint=false and destructiveHint=false. The description adds 'Authorization class: board,' which provides authorization context beyond annotations. However, it does not disclose idempotency, rate limits, or side effects, which are partially covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) and front-loaded with the purpose. However, it omits essential parameter information, making it incomplete rather than efficient.
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 tool has complex nested parameters and no description of them. The description does not explain what the token is used for, how long it lives, or prerequisites. Given the output schema existence, return value explanation is not needed, but parameter context is severely lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of parameters such as 'scope', 'grantId', 'subject', or 'requestedTtlSeconds'. With this gap, the description fails to help the agent understand parameter meaning.
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 title and description both clearly state 'Mint a short-lived token for an agent connection,' using a specific verb ('mint') and identifying the resource (agent connection). This distinguishes it from sibling tools, though the purpose of the token (e.g., authentication scope) is not elaborated.
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 on when to use this tool versus alternatives. Sibling tools like connection grant operations exist but are not mentioned. The description includes 'Authorization class: board' as a hint but does not explicitly state usage context 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?
Annotations already signal a non-read-only, non-destructive mutation. The description adds the authorization class (board_or_agent), which is helpful. However, it doesn't describe the outcome of approval (e.g., state change, side effects). With annotations covering safety, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the action. It efficiently states the purpose and technical details, though it omits parameter context.
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 two required parameters and no schema descriptions, the description is too sparse. It fails to explain what the tool accomplishes beyond the name, and parameter semantics are missing. Output schema exists but doesn't compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description provides no explanation of parameters (path.id, body.decisionNote). The agent is left without guidance on required or optional inputs.
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 the verb 'Approve' with the resource 'an approval', clearly indicating the action. It distinguishes from sibling tools like reject, resubmit, and request revision, though it doesn't explicitly name them.
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 on when to use this tool versus alternatives (e.g., reject, resubmit, request revision). The description only provides HTTP operation and authorization class, not usage 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 indicate destructiveHint=true and readOnlyHint=false. The description adds the HTTP method (POST) and endpoint, but does not elaborate on side effects (e.g., status change, notifications). It provides modest additional context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences), with no unnecessary information. However, the first sentence repeats the title, and the structure could be improved by front-loading the most critical details (e.g., what is needed to reject).
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 destructiveHint=true and no explanation of prerequisites, the description leaves ambiguity about when rejection is valid (e.g., only pending approvals). Output schema exists but is not referenced. The description is insufficient for safe, informed use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It does not mention that 'id' is the approval ID or that 'decisionNote' is an optional reason. The description provides no parameter-level details, failing to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Reject an approval' which clearly indicates the verb and resource. The tool name also contains 'reject'. However, it does not explicitly differentiate from sibling tools like approve or request revision, though the action is distinct enough.
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 on when to use this tool vs alternatives (approve, request revision, resubmit). The only contextual hint is the authorization class 'board_or_agent', which implies who can use it. No description of prerequisites or 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?
The description only restates the HTTP method and authorization class, which are already implied by the tool name and annotations. Annotations already indicate non-read-only and non-destructive, but the description does not explain what 'claiming' entails or any side effects. No additional behavioral context is provided beyond what annotations offer.
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 includes technical details like 'Paperclip operation' and 'Authorization class' which are likely noise for an AI agent. It could be more streamlined, but it is not overly verbose. Front-loading is acceptable.
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?
While an output schema exists, the description omits any mention of return values or effects. For a mutation tool with 2 parameters and no behavioral guidance, the description is incomplete. The agent lacks information to understand the tool's full behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no explanation of the 'token' path parameter or the optional body. With only 50% schema description coverage, the schema itself has minimal descriptions (body description is generic). The tool description adds zero value for parameter understanding, leaving the agent to guess.
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 title 'Claim a board token' and description clearly state the action and resource. The HTTP method and path are provided, distinguishing it from the sibling 'pc_get_board_claim_by_token' which likely retrieves claim info. The purpose is 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 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 like 'pc_get_board_claim_by_token'. There is no mention of prerequisites, typical use cases, or when not to use it. The agent must infer context from the tool 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?
Annotations already indicate readOnlyHint=false (write) and destructiveHint=false. The description adds that authorization is 'public', which is useful. However, it does not disclose what happens upon creation (e.g., returns a challenge ID, requires approval) or other behavioral traits.
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 concise with two sentences containing essential information (purpose, HTTP details, auth class). No unnecessary words, but could be better structured with distinct sections.
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 presence of an output schema and zero parameter descriptions, the description is incomplete. It does not explain the response, when to use, or parameter meanings, leaving significant gaps for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation for any parameter. Agents must rely solely on parameter names ('command', 'clientName', etc.), which may be insufficient for correct invocation.
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 creates a CLI auth challenge, with a specific verb and resource. It also specifies the HTTP method and path. However, it does not distinguish from sibling tools like approve or cancel, which have different purposes.
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 on when to use this tool versus sibling tools (e.g., pc_post_cli_auth_challenges_by_id_approve). No prerequisites, context, or alternatives 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?
Annotations already indicate non-read-only and non-destructive. The description adds the authorization class ('board'), providing some behavioral context. However, side effects of creating a push run are not explained.
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 short but includes redundant implementation detail ('Paperclip operation: ...'). It could be front-loaded better. Acceptable but could be improved.
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 complexity (nested parameters, required fields, and an output schema), the description lacks explanation of what a cloud upstream push run is and what the return value represents. Incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description provides no meaning for any parameter. Parameters like connectionId, companyId, and retryOfRunId remain unexplained.
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 ('Create') and resource ('cloud upstream push run'). The HTTP path is provided but sibling differentiation (e.g., vs preview) is not explicitly mentioned.
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 on when to use this tool versus alternatives like the preview endpoint. Prerequisites (e.g., existing connection) are not indicated.
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 non-read-only, non-destructive operation. The description adds the authorization class ('board'), providing some behavioral context. However, it does not describe side effects, idempotency, or whether the operation blocks or initiates an async process.
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 very short (two sentences) and avoids verbosity. The first sentence restates the title, which is acceptable but not ideal for front-loading. Still, it is appropriately sized for a simple 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?
Despite having an output schema, the description lacks important context about the connection process (e.g., that this starts an OAuth flow, requires a callback, or that a follow-up 'finish' step is needed). The agent cannot fully understand the tool's role in the broader workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has three nested properties (companyId, remoteUrl, redirectUri) with 0% schema description coverage. The description does not explain what these parameters are or how they should be used, leaving the agent unable to infer their purpose.
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 ('Start a cloud upstream connection') and provides the HTTP method and path. However, it does not distinguish this from the sibling tool 'pc_post_cloud_upstreams_connect_finish', which is part of the same flow.
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 prerequisites (e.g., that an upstream must already exist) or indicate that this is the first step in an OAuth-based connection process.
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?
Description adds authorization class ('board_or_agent') beyond annotations, which is helpful. However, it omits behavioral details such as state changes, side effects, or what happens after resolution. Annotations already indicate non-readOnly and non-idempotent, so the description adds marginal value.
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 very short (two sentences) and to the point. However, the second sentence is technical (Paperclip operation, authorization) and could be more user-friendly. It is concise but at the expense of completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested objects, 2 required params, 0% schema description coverage, and no output schema explanation), the description is severely lacking. It does not clarify the meaning of 'resolve', the role of 'action', or the consequences of the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain any parameters. Critical fields like 'action' (enum with values 'keep_paused' and 'raise_budget_and_resume') and 'amount' are left unexplained, forcing reliance on external knowledge.
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 ('Resolve') and the resource ('budget incident'), and includes the HTTP method and endpoint path for precision. However, it does not elaborate on what 'resolve' entails (e.g., the two possible actions), limiting full 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?
No when-to-use or when-not-to-use guidance is provided. Sibling tools include other budget-related operations, but the description does not distinguish this tool from alternatives or suggest appropriate contexts.
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?
Adds authorization class info beyond annotations. However, does not mention side effects, idempotency behavior, or handling of updates vs creates. With openWorldHint=true, the description should note that extra fields may be accepted. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no wasted words, but overly brief. Lacks essential details; conciseness is achieved at the expense of completeness. Could be improved by including parameter guidance while maintaining 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 the tool's complexity (nested body, required fields, output schema), the description is incomplete. It does not explain what a budget policy is, how create vs update is determined, or what the output contains. Agent lacks context to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of parameters (amount, scopeType, scopeId, etc.). The nested structure and required fields are entirely undocumented, forcing the agent to rely solely on the schema. This is a critical gap.
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?
Clearly states 'Create or update a budget policy', specifying the verb and resource. However, it does not differentiate from sibling budget tools like pc_get_companies_by_company_id_budgets_overview (read) or pc_patch_companies_by_company_id_budgets (patch budgets), missing an opportunity to clarify scope.
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 on when to use this tool versus alternatives (e.g., when to use post vs patch for budget policies). Missing prerequisites or context for creation vs update. The description only states the HTTP method and auth class, which is insufficient for decision-making.
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 mentions the HTTP method (POST) and authorization class ('board_or_agent'), which adds some behavioral context. Annotations already indicate readOnlyHint=false, openWorldHint=true, etc., so the description does not contradict but also does not elaborate on side effects or idempotency 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) and avoids redundancy. However, it sacrifices informative content for brevity, leaving out essential details about parameters and behavior. It is concise but not sufficiently explanatory.
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 (3 path parameters, an output schema, and many sibling tools for built-in agents), the description lacks crucial context. It does not mention the output schema, what the routine execution entails, or any post-run effects. An AI agent would have insufficient information to use this tool appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning parameter descriptions are entirely missing. The tool's description only restates the path pattern but does not explain the meaning or valid values of the parameters (companyId, key, routineKey), nor the purpose of the empty body. This is a critical gap.
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 'Run a built-in routine once', which uses a specific verb ('Run') and identifies the resource ('built-in routine'). The HTTP method and path are provided, adding clarity. However, it does not explicitly differentiate from other built-in agent tools like reset or provision, which are also POST operations on built-in agents.
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 (e.g., other built-in agent tools like reconcile, provision, reset). It lacks context for decision-making, such as prerequisites or side effects.
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 mark destructiveHint=true, so the description's mention of 'Disable' aligns. The description adds the authorization class 'board_or_agent', but does not disclose side effects, reversibility, or failure modes. Some value added but limited.
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 very concise with two sentences, front-loading the purpose and then providing the endpoint and auth. Every word earns its place, though it could be slightly improved by including a high-level parameter hint without becoming verbose.
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 the presence of an output schema, the description fails to provide context about the resource hierarchy (built-in agents, routines), how to obtain the required keys, or what the disable operation entails. This leaves the agent underinformed for a three-parameter destructive action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should explain parameter meanings. It only shows the endpoint path but does not describe what 'key' or 'routineKey' represent, leaving the agent without guidance for correct parameter values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Disable' and the resource 'built-in routine schedule', making the tool's purpose immediately understandable. However, it does not explicitly distinguish this tool from sibling tools like enabling or provisioning built-in agents, so it falls short of a perfect 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 context on when to use this tool versus alternatives (e.g., enabling, resetting). It only specifies the operation and authorization class, but fails to guide the agent on appropriate usage scenarios.
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, not destructive, not idempotent. The description adds that it is a POST operation and requires board_or_agent authorization. However, it does not disclose potential side effects, reversibility, or impact on managed resources.
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 concise with only two sentences. However, the first sentence is essentially a repeat of the title, which wastes space. It is still efficient but could be more informative.
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 complexity (2 path parameters, empty body, output schema), the description is too brief to be complete. It does not explain the purpose beyond 'reconcile', leaving the agent without enough context to decide when to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation for the 'path' or 'body' parameters. The body is empty in schema but could have hidden semantics; the description fails to clarify.
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 the tool reconciles built-in agent managed resources, using a POST operation. While it identifies the specific action, it does not elaborate on what reconciliation entails, leaving some ambiguity. It distinguishes from siblings by the 'reconcile' verb, but lacks clarity on the exact outcome.
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 on when to use this tool versus other built-in agent tools like provision, reset, or status. The description does not specify prerequisites, scenarios, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a write operation but not destructive. Description adds authorization class (board_or_agent) but does not disclose side effects, idempotency implications, or rate limits. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the core purpose. It could be more informative about parameters without adding much length.
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 complexity of the input schema (many fields, nested objects) and the presence of an output schema, the description lacks essential details about parameters and return value, making it insufficient for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of any parameter, despite many required and optional fields in the body.
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 title and description clearly state that the tool records a cost event. The purpose is evident, but it does not differentiate itself from sibling cost-related tools beyond the verb 'record.'
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 on when to use this tool versus alternatives, no prerequisites, no exclusions, and no context about when recording cost events is appropriate.
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, idempotentHint=false, and destructiveHint=false, so the agent knows this is a non-idempotent, non-destructive write operation. The description adds the authorization class 'board_or_agent', which is useful context beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, but it repeats the title 'Capture a decision training example' and adds endpoint and authorization info. It could be more concise by integrating the endpoint info into the purpose. However, it is front-loaded and not verbose, earning a middle 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?
Given the tool's complexity (POST endpoint with nested body parameters), the description is incomplete. It fails to explain the meaning of required body fields (sourceKind, issueId, sourceId) and the optional notes field. The output schema exists, so return values are covered, but the overall description lacks sufficient detail for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, meaning no parameter descriptions are provided. The tool description also fails to explain any parameters (sourceKind, sourceId, issueId, notes, companyId), leaving the agent without guidance on required fields, allowed values, or format. This is a critical gap.
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 'Capture a decision training example', which is a clear verb+resource indicating the tool creates a decision training example. It distinguishes from siblings like 'pc_post_companies_by_company_id_decision_training_preview' by being the actual capture action, though the exact nature of 'decision training example' is somewhat vague.
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 guidelines are provided. The description does not indicate when to use this tool versus the preview tool or other related tools. There is no mention of prerequisites, when-not-to-use, or alternatives, leaving the agent to infer usage from context 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 description adds the authorization class (board_or_agent) but does not exceed the annotations significantly. It does not contradict annotations, but the POST method combined with 'Get' may be misleading; however, no clear contradiction.
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 short but includes redundant implementation details like 'Paperclip operation' and 'Authorization class'. It is front-loaded with the purpose but wastes space on internal API info.
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 tool has moderate complexity with nested objects and an output schema, but the description lacks context about what the summaries contain, when to use it, and how it relates to similar tools. It feels incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description provides no explanation of parameters. The body and path parameters are completely undocumented in the description, leaving the agent with only 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 title and description clearly state that the tool gets external object status summaries for issues. The verb 'Get' and resource are explicit, but there is no differentiation from sibling tools like pc_get_issues_by_id_external_object_summary.
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 the sibling that gets a single summary. There is no mention of context 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 indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, so this is a non-idempotent write operation. The description adds the 'Authorization class: board_or_agent' which is useful context not covered by annotations. However, it does not disclose potential side effects like triggering workflows or creating sub-resources.
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 (three lines) and front-loaded, but it omits essential information about parameters and usage. Conciseness is valued, but it sacrifices completeness. A few more sentences would improve it without losing 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 the tool's complexity (many params, nested objects, numerous sibling tools for routines), the description is insufficient. It does not explain when to create a routine versus other actions, nor does it clarify the meaning of key fields. The output schema exists, so return values are not required, but input semantics are critically missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has many parameters (companyId, title, status, env, goalId, etc.) with complex nested objects, yet the description adds no parameter explanations. Schema description coverage is 0%, so the agent must rely solely on the schema, which may be insufficient for correct usage. This is a significant gap.
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 'Create a routine' with the HTTP method and path, making the action and resource specific. It distinguishes from sibling tools like pc_patch_routines_by_id or pc_get_routines_by_id which are different operations. However, it does not elaborate beyond the title, so it's clear but minimal.
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 on when to use this tool versus alternatives (e.g., patching or fetching routines). It does not state prerequisites, such as needing a company ID or the required authorization level being board_or_agent. The agent would need to infer context from sibling tool names.
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 provide readOnlyHint, destructiveHint, and openWorldHint. Description adds only endpoint and auth, no further behavioral context. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is very short (two sentences), front-loads purpose. Could be more informative without being verbose.
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, the description lacks context about the preview function, input requirements, and expected behavior. Incomplete for a tool with complex schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning no parameter descriptions are in the schema. The description fails to explain any parameters, such as required companyId and provider, or optional fields like query, config, pageSize, nextToken.
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?
Description clearly states the tool previews secret provider discovery. The verb 'Preview' and resource are specific, but lacks explicit differentiation from sibling tools like pc_get_companies_by_company_id_secret_providers.
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 on when to use this tool versus alternatives like health checks or config management. Only HTTP method and authorization class are 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 indicate non-readonly and non-destructive. The description adds the authorization class 'board_or_agent' beyond annotations, but does not disclose other behavioral traits like idempotency or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise (3 lines), but lacks substance. Every sentence is short, yet the description is too sparse to be fully helpful.
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 complexity of the input schema (10 body properties) and no output schema details, the description is woefully incomplete. It does not explain return values or typical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description provides no information about the 2 required parameters (path and body) or their properties. The agent must infer meaning from the schema alone.
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 title 'Create a secret' and description clearly state the action and resource. However, it does not differentiate from sibling tools like pc_patch_secrets_by_id or pc_delete_secrets_by_id beyond the verb.
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 on when to use this tool versus alternatives such as patch or delete operations. The description only repeats the title and adds HTTP method and auth class.
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 readOnlyHint=false, openWorldHint=true, etc. Description adds only endpoint and auth class, not explaining side effects or what evaluation entails. Does not disclose behavioral traits beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is brief (two sentences plus endpoint info) and front-loaded, but could be more informative without being verbose.
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 complexity (nested input, output schema exists), description is insufficient. No mention of return values, prerequisites, or behavior beyond the endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. Description does not explain any parameter meaning or usage, leaving the agent to infer from names and enums only.
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?
Title and description clearly state 'Evaluate a company skill policy decision'. The verb 'evaluate' and resource are specific. However, no explicit differentiation from sibling tools (get/put/delete policy) is provided.
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 on when to use this tool versus alternatives. Description lacks context for appropriate use cases 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?
Adds authorization class ('board_or_agent') which isn't in annotations, providing useful access context. However, it fails to describe the behavioral effects of forking (e.g., what gets created or modified). Annotations indicate readOnlyHint=false (write operation) and destructiveHint=false (not destructive), but the description doesn't elaborate on side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very brief (two sentences), no wasted words. However, the brevity sacrifices essential information. The structure is clean but incomplete. The title is repeated verbatim, which is unnecessary.
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, the description fails to explain what the tool does beyond the name. It doesn't state the outcome of forking (e.g., creates a new skill, returns a skill ID). The context signals indicate complexity with nested objects, yet the description provides no behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description provides no explanation of parameters. The 'body' parameter is an open object with no constraints, and path parameters are just string IDs. No additional meaning is added beyond the schema. This is inadequate for a tool with 2 required 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 'Fork a company skill', using a specific verb and resource. 'Fork' is a standard action in version control contexts, making the purpose distinct from sibling tools like create, update, or delete. However, it doesn't elaborate on what forking entails (e.g., whether it creates a copy within the same company or across companies), which slightly reduces 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?
No guidance on when to use this tool versus alternatives. There is no mention of when forking is appropriate compared to creating a new skill or updating an existing one. The description lacks explicit usage context or exclusion criteria.
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 add any behavioral context beyond the annotations. Annotations already indicate it is not read-only, not idempotent, and not destructive. No mention of side effects, required permissions beyond 'board_or_agent', or what happens after installation.
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 very short and to the point, with no unnecessary words. However, it is overly terse and sacrifices informational value 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 the tool's complexity (2 parameters, output schema) and the existence of many sibling tools, the description is insufficient. It does not explain what 'install update' does, expected input, or outcome. Even with annotations, the context is inadequate.
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 description does not explain the purpose or format of the parameters (body, path). Schema coverage is 50%, but the parameter descriptions are absent or minimal (body has a vague note). The agent gets no extra meaning from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The title 'Install a skill update' and description clearly state the verb and resource. It distinguishes itself from related sibling tools like get_update_status, patch, and delete. However, it lacks a brief explanation of what 'install update' entails (e.g., applying a pending update), so it's not 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 on when to use this tool versus alternatives, such as checking update status first or prerequisites. The description only provides the HTTP method and auth class, leaving the agent with no context for decision-making.
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 adds the HTTP method (POST) and authorization class, which are beyond the annotations. However, it does not disclose side effects, creation behavior, or return value details. Annotations already indicate non-readOnly, non-idempotent, non-destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) and front-loaded with the purpose, but it omits critical details. It is concise but not well-structured for aiding tool invocation.
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 complexity of the input schema (nested objects, multiple optional fields) and no schema descriptions, the description is inadequate. It does not explain how to construct the body or what the output contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no information about the parameters. With 0% schema description coverage, the agent gets no guidance on what each field (agentId, content, etc.) means or how to use them.
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 'Create a skill test run', which is a specific verb and resource. It matches the title and distinguishes the tool from siblings like list/get/delete. However, it doesn't elaborate on what a test run is.
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 on when to use this tool versus alternatives (e.g., listing or getting test runs). The authorization class is mentioned but does not help with usage decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds the authorization class (board_or_agent) and the manual generation aspect, but does not elaborate on side effects like overwriting vs creating new slots, rate limits, or other behavioral traits.
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) and repeats the title. While concise, it omits important information about parameters and usage, making it minimally adequate.
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 complexity (nested objects, multiple parameters, many sibling tools), the description fails to provide sufficient context. It does not explain the meaning of parameters, when to use this tool, or what the output is, despite having an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no descriptions for the parameters in the schema. The description does not explain any of the parameters (companyId, scopeKind, slotKey, scopeId) beyond the URL pattern, leaving meaning unclear.
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?
Title and description clearly state the tool is for manually generating or refreshing a summary slot. The HTTP method (POST) distinguishes it from sibling tools for GET and PUT operations, but the description does not explicitly differentiate when to use this vs siblings.
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 pc_get_companies_by_company_id_summary_slots_by_scope_... or pc_put_companies_by_company_id_summary_slots_by_scope_.... The description only gives the endpoint and auth class, with no context on use cases 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 indicate this is a non-read-only, non-idempotent mutation (readOnlyHint: false, idempotentHint: false). The description adds the HTTP POST method and path but does not elaborate on behavioral effects (e.g., triggering a redirect, returning a URL, or modifying connection state). 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at two sentences, free of fluff. It repeats the title and provides the operation path. However, it lacks structure or bullet points for readability.
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 2 parameters with nested objects and 0% schema coverage, the description is highly incomplete. It omits details about the authorization flow, response contents (despite an output schema existing), and any side effects. The agent cannot determine how to use the tool effectively based solely on this description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description does not explain any parameter (subjectUserId, scopes, returnTo, companyId, connectionId). Parameter names are somewhat self-descriptive, but the purpose of each, especially the nested fields, is not articulated, leaving the agent to infer from schema structure alone.
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 title and description clearly state 'Start user authorization for a tool connection' with a specific verb and resource. The operation path is included, distinguishing it from sibling tools like 'pc_get_tool_connections' or 'pc_post_tools_oauth_by_connection_id_start'. However, the description is minimal and could further clarify the exact scope of the authorization.
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 (e.g., 'pc_post_tools_oauth_by_connection_id_start' or other connection tools). It does not mention prerequisites, such as whether a connection must already exist, or context for when authorization is needed.
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 a write operation (readOnlyHint: false) and not destructive. The description adds context about the HTTP method and authorization class ('board'), but does not further explain behavioral traits like side effects or idempotency.
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 but lacks necessary detail. It could be expanded to include parameter hints or usage context without being 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 complexity of creating a tool access profile (nested objects, many fields, output schema exists), the description is incomplete. It fails to explain crucial aspects like how to define entries or set default actions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 2 parameters with 0% schema description coverage. The description does not mention any parameters, adding no value beyond the schema itself.
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 'Create a tool access profile', which is a specific verb-resource pairing. However, it does not differentiate from sibling tools like listing or updating profiles.
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 updating or deleting profiles. The description lacks any when/when-not or alternative suggestions.
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 write (readOnlyHint=false) and non-destructive (destructiveHint=false), but the description adds no behavioral context beyond the basic function. It doesn't mention whether binding overwrites existing bindings, side effects, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two sentences) but the second sentence, providing the API endpoint and authorization class, adds little value beyond what the tool name implies. It could be more informative while remaining 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 openWorldHint=true and a nested input schema, the description should explain side effects and the output (e.g., success indication). It does not mention what the tool returns or the impact of binding a profile. Incomplete for a complex write operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of parameters (targetType, targetId, priority, metadata). The description lists some target types but omits 'gateway' from the enum. The agent must rely solely on the schema names, which is insufficient.
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 (bind), the resource (tool access profile), and lists the possible target types (company, agent, project, routine, issue). It distinguishes this tool from sibling profile CRUD tools by specifying the 'bind' 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 on when to use this tool vs alternatives (e.g., creating or editing a profile). No prerequisites (e.g., existing profile and target) or scenarios are mentioned. The authorization class is given but not explained in terms of 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 indicate destructiveHint=true and readOnlyHint=false, so the description's value is limited. It adds 'Authorization class: board_or_agent', which is helpful, but no additional behavioral details (e.g., session state changes, side effects).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with purpose, but lacks essential parameter explanations. It could include more detail without becoming verbose.
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 2 required parameters, 0% schema coverage, and an output schema, the description does not explain parameter usage, return value, or cancellation behavior. It feels incomplete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain any parameter. The schema defines body.reason (string 1-1000 chars) and path.sessionId, but neither is mentioned.
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 (cancel) and the resource (environment customImage setup session). It also provides the HTTP method and path. However, it does not differentiate from sibling tools that also operate on sessions (e.g., get, start).
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 on when to use this tool versus alternatives. Does not specify prerequisites, when cancellation is appropriate, or scenarios to avoid.
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 non-readOnly and non-destructive, which the description complements by stating the token is short-lived. However, it does not disclose side effects, token lifespan specifics, or what happens to the session after token creation.
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 with two sentences, but the second sentence about Paperclip operation and authorization class is technical and may not be actionable for an AI agent. Still, it is efficient and 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 fails to mention that the token is for websocket communication or that a custom image setup session must already exist. Output schema exists but is not shown, yet the description offers no clue about the response content (e.g., token string).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description provides no explanation for the required sessionId parameter. The body is empty, but the agent gets no hint on how to obtain or use sessionId. This is a critical gap.
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 mints a short-lived websocket token for a customImage SSH setup session, specifying the verb 'mint' and resource 'terminal websocket token'. However, it does not differentiate from sibling tools like pc_post_environment_custom_image_setup_sessions_by_se_4137e3652d, which may perform a related action.
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 on when to use this tool versus alternatives. It does not mention prerequisites (e.g., an existing custom image setup session) or scenarios where this token is needed. There is no when-not-to-use information.
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 nature. The description adds that it is a 'finish' action, but does not explain what 'promote' means or the state changes. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, but the second sentence is technical (Paperclip operation, auth class). No wasted words, but it could be more informative without being verbose.
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 output schema exists but is not shown, the description fails to describe what happens after the session is finished (e.g., custom image becomes available). No error scenarios or success conditions are mentioned. The tool's purpose is too vaguely conveyed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain what the metadata object or sessionId parameter are used for. The agent must rely entirely on the schema names, which is insufficient.
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 it captures and promotes an environment customImage setup session, with a specific HTTP method and path. However, it does not distinguish itself from sibling tools like pc_post_environment_custom_image_setup_sessions_by_se_0fc4883e16, which may perform a different action.
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 on when to use this tool versus alternatives. It mentions an authorization class but does not indicate prerequisites (e.g., an active session must exist) 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (write operation) and destructiveHint=false (not destructive). The description adds that it is a POST operation and the authorization class. This is minimal additional context beyond annotations. The openWorldHint=true suggests side effects, but the description does not elaborate.
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 short but the second sentence about Paperclip operation and authorization class is technical and may not be useful for an AI agent. It could be more concise by focusing on the tool's behavior rather than the raw API endpoint.
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 tool has an output schema and 3 parameters, but the description is incomplete. It does not explain what a 'customImage setup session' is, what it does, or what the response contains. With 0% parameter coverage, the description fails to provide essential context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It does not. The parameters environmentId, templateId, ttlSeconds, and companyId are not described. The agent cannot infer their meaning or usage from the description alone.
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 starts an interactive environment customImage setup session. The verb 'start' and resource 'customImage setup session' are specific. However, it does not differentiate from sibling tools like pc_post_environments_by_environment_id_custom_image_t_e61e5957bf (which appears to set a template) or pc_get_environments_by_environment_id_custom_image_template.
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 vs alternatives. It does not mention prerequisites, when to use (e.g., needing to set up a custom image interactively), or when not to use. The authorization class mention is a technical detail, not usage 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?
The description adds the HTTP method (POST) and authorization class, which are beyond the annotations. However, it does not disclose side effects, return value, or error conditions. Annotations already indicate it is not read-only and not destructive, so the description adds moderate value.
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 very short and front-loaded with the core purpose. It consists of two concise sentences. However, it sacrifices completeness for brevity, which is acceptable given the minimal context.
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 complexity of the input schema, the absence of output schema description, and the high parameter count, the description is insufficient. It does not explain what happens after submitting decisions, how decisions are interpreted, or the meaning of the body fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has significant complexity (nested objects, required fields) and schema coverage is 0%. The description provides no information about the parameters or their meanings. This is a critical gap that severely hinders correct invocation.
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 verb 'Submit' and the resource 'watchdog decisions for a run'. It matches the title and is distinct from sibling tools by specifying the core action. However, it does not distinguish itself from potentially similar tools like pc_put_issues_by_id_watchdog.
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 prerequisites, typical scenarios, or when not to use it. The only extra context is the authorization class, which is minimally helpful for usage decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the authorization class 'board_or_agent' which provides behavioral context beyond annotations. However, it does not disclose other important behaviors like side effects on the parent issue or subtree, or whether creation is synchronous. Annotations already indicate non-read-only and non-destructive, so the description adds mild value.
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 very concise, consisting of two short sentences. There is no fluff, and the technical details (operation, authorization class) are efficiently presented. However, it lacks structure that could improve scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high complexity (many parameters, nested objects, output schema), the description is extremely incomplete. It does not explain the purpose of the parent ID, required fields in the body, or typical usage. Even with an output schema, the description fails to provide sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not describe any parameters. With 0% schema description coverage, it provides no guidance on the required 'path.id' (parent issue ID) or the complex 'body' object fields. The input schema is comprehensive but the description adds nothing, leaving the agent without usage hints.
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 'Create child issues' with the endpoint POST /api/issues/{id}/children, clearly indicating it creates a child issue for a given parent. The verb-resource pair is specific and distinguishes it from general issue creation endpoints like pc_post_companies_by_company_id_issues.
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 other issue creation endpoints. There is no mention of prerequisites, parent issue requirements, or typical use cases.
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-read-only, non-destructive, and non-idempotent. The description adds authorization class 'board_or_agent', but does not elaborate on upsert semantics (e.g., behavior if vote exists) or other side effects. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundancy. However, it is too brief, missing important details that would justify its length. Balance of conciseness and completeness is off.
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, the description fails to explain the operation's purpose (upsert meaning), parameter roles, or when it applies. Minimal context for a tool with nested parameters and an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain any parameters or their fields (e.g., what 'vote', 'targetType', 'reason' mean). It relies entirely on the schema, which lacks descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Upsert a feedback vote' with a specific verb and resource. It also provides the HTTP method and path. However, it does not explicitly distinguish from sibling tools like pc_get_issues_by_id_feedback_votes, which list votes.
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 on when to use this tool versus alternatives (e.g., when to upsert vs. other feedback operations). No usage context or exclusions 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 destructiveHint: true, so the description adds some value by specifying the authorization class ('board_or_agent') and the HTTP method. However, it does not explain what releasing a hold entails or its effects on the issue tree, missing an opportunity to enhance transparency 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (two sentences), but it sacrifices substance for brevity. While it is well-structured with the action first, the second sentence is technical boilerplate. It could be more informative 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 nested objects, an output schema, and is a destructive operation, the description is incomplete. It fails to explain the purpose of body fields (reason, metadata, releasePolicy) and does not describe the output. The tool's complexity demands more detail than provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the schema itself provides no descriptions for parameters. The description does not mention or explain any of the input parameters (id, holdId, reason, metadata, releasePolicy). It fails to compensate for the lack of schema descriptions, leaving the agent without guidance on parameter 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 'Release an issue tree hold', which is a specific verb ('release') and resource ('issue tree hold'). It avoids tautology and is somewhat distinguishable from sibling tree hold tools, though it does not explicitly differentiate from other release operations like pc_post_issues_by_id_release.
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., pc_post_issues_by_id_release for issue-level release, or pc_post_issues_by_id_admin_force_release). There is no mention of prerequisites, such as the existence of a hold or required authorization beyond the class listed.
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 not read-only, not destructive, not idempotent. The description adds 'Authorization class: public' which is helpful. However, it does not describe side effects, request handling details, or what happens on success/failure. More context about the MCP protocol would improve transparency.
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 lines plus extra metadata). It is concise but lacks a structured format (e.g., bullet points or sections). The inclusion of operation and authorization class is efficient, but the brevity sacrifices clarity.
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 tool has a complex schema with nested objects and an output schema, yet the description provides almost no context. An agent would struggle to use this tool correctly due to missing parameter explanations and lack of behavioral context. The description is too minimal for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. Neither the description nor the input schema explains the parameters. The body and gatewayPublicId are not described in the description. The agent gets no guidance on what values to provide, especially for the free-form body object.
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 handles MCP gateway protocol requests by public ID. The verb 'handle' is somewhat generic but the resource and scope are clear from the path and operation. However, it does not differentiate from sibling tools like pc_get_mcp_gateways_by_gateway_public_id or other gateway-related 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 on when to use this tool versus alternatives. The description does not explain prerequisites, context, or situations where this tool is appropriate. It only provides the operation and authorization class, which is not enough for an agent to decide when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds minimal behavioral context beyond the HTTP method and authorization class. There is no mention of effects like downtime, version changes, or rollback possibilities. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, consisting of two short sentences with no fluff. However, it may be too minimal for adequate understanding, but conciseness itself is well-served.
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 (unseen), the description fails to explain what upgrading entails (e.g., version specification, confirmation of completion). It omits important context for a mutation tool, leaving the agent underinformed.
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 50%, with body having a description ('Optional JSON compatibility payload...') but no detail on path/pluginId. The description does not add any parameter meaning beyond the schema, leaving the agent to infer the role of pluginId.
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 title and description clearly state 'Upgrade a plugin', using a specific verb and resource. It is distinguishable from sibling tools like install, enable, disable, etc., though no explicit differentiation is provided.
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 lacks any guidance on when to use this tool versus alternatives, such as prerequisites (plugin installed, enabled) or context (e.g., upgrading to latest version). No when-not or exclusion criteria are mentioned.
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 basic hints (non-readonly, non-destructive, non-idempotent, open-world), but the description does not add meaningful behavioral context beyond the API endpoint. It omits details about installation process, side effects, or what constitutes a successful installation.
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 short and front-loaded, but it sacrifices necessary information. It could add parameter explanations or usage context without becoming overly verbose.
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 presence of an output schema and annotations, the description still fails to cover key aspects like installation behavior, error conditions, or relationship to sibling tools. It is incomplete for an AI agent to use reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description provides no explanation of parameters (packageName, version, isLocalPath). An agent would not know what values to provide or their semantics, making this a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Install a plugin' with a specific verb and resource, and distinguishes from sibling tools by providing the API endpoint and auth class. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Authorization class: instance_admin' which hints at when to use, but it lacks explicit guidance on when to use this tool versus alternative plugin tools like enable, disable, or upgrade. No context about prerequisites or consequences.
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 provide readOnlyHint, idempotentHint, destructiveHint. The description adds only authorization class and HTTP path, not disclosing behaviors like idempotency or side effects of creating a workspace.
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 lacks depth; it is concise but not informative. Each sentence adds minimal value, but there is no waste.
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, the description omits crucial context about what a project workspace is, prerequisites, and how the body fields relate to the creation. Incomplete for a complex tool with many parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description provides no parameter explanations. With many nested and optional properties, the tool description adds no value in understanding what inputs 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 explicitly states 'Create a project workspace' with the HTTP method/path, clearly identifying the action and resource. Among siblings, it distinguishes as the create operation for project workspaces vs. list, patch, and delete.
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 on when to use this tool versus alternatives like patching or deleting workspaces. The description lacks context for selecting this tool appropriately.
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 provide readOnlyHint=false, idempotentHint=false, destructiveHint=false, which indicate write but not destructive. The description adds the authorization class ('board_or_agent'), which is useful. However, it does not disclose that running a routine creates a run resource, or that using idempotencyKey can prevent duplicates. The description adds some value beyond annotations but could be richer.
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) and front-loaded with the main action. However, the inclusion of internal details like 'Paperclip operation: POST /api/routines/{id}/run' and 'Authorization class: board_or_agent' are not essential for an AI agent and take space that could be used for parameter descriptions. It is concise but at the expense of completeness.
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 (many body parameters, nested objects, output schema exists), a single-sentence description is insufficient. It does not explain the purpose of the body, the effect of the run, or how to use the optional fields. The description is far from complete for an agent to invoke the tool correctly without additional knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate. It does not describe any parameters: the required path (routine ID) or the body fields (source, payload, variables, etc.). No guidance on what each parameter does or how to use them. This is a critical gap for a tool with many 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 states 'Manually run a routine', which is a clear verb+resource. It distinguishes from sibling tools like pc_get_routines_by_id (read) or pc_post_routines_by_id_triggers (create trigger). However, it does not explain what 'run' means in terms of effect (e.g., triggers execution), so not 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 explicit guidance on when to use this tool versus alternatives. It does not mention when a manual run is appropriate or when to use other tools like pc_get_routines_by_id_runs or triggers. The agent must infer usage from the tool 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 indicate this is a destructive write operation (readOnlyHint false, destructiveHint true). The description adds only 'Authorization class: board', which provides some auth context but no details on side effects, what declining entails, or any irreversible consequences.
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 short (two sentences) but the first sentence merely repeats the title. The second sentence gives technical details. It is concise but lacks substantive content for the agent.
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 presence of an output schema, return values need not be explained. However, for a destructive action with three undocumented parameters, the description should provide more behavioral context and parameter guidance. It falls short.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about the three parameters (path.id, body.companyId, query.companyId). The agent cannot infer how to set these parameters correctly from the description alone.
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 it declines a deferred tool gateway action request. The verb 'decline' is specific and distinguishes this tool from sibling tools like the approve tool.
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 on when to use this tool vs alternatives. The sibling tools include an approve action, but the description does not explain conditions for declining versus approving, nor any prerequisites or 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?
Annotations indicate a write operation (readOnlyHint=false) but description adds no behavioral details like side effects, return value, or security implications.
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, with two sentences. The second sentence is technical and not helpful for tool selection, but the first is clear.
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, the description does not mention what the tool returns, leaving the agent without critical information for a creation operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not explain the required parameters (gatewayId, companyId), leaving their purpose unclear.
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 ('Create') and resource ('MCP gateway token'), with the title adding 'named'. This distinguishes it from the sibling revoke token tool.
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 on when to use this tool versus alternatives, such as when to revoke tokens. No prerequisites or context 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 indicate destructiveHint=true and readOnlyHint=false. The description adds the authorization class 'board', providing extra behavioral context beyond annotations. However, it does not detail consequences of revocation or whether it is reversible.
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 concise (two short sentences) but omits important information like parameter details and usage context. The technical details (HTTP method, path, auth class) are front-loaded, but conciseness sacrifices completeness.
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 output schema exists, return values are not needed. However, the description lacks explanation for the required body parameter (companyId) and fails to provide usage context. The tool's complexity (nested path, destructive action) is not adequately addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% with no parameter descriptions, and the tool description does not explain the parameters. The body parameter (companyId) is completely undocumented, leaving the agent without guidance on its purpose or format.
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 title and first sentence clearly state 'Revoke a named MCP gateway token', which is a specific verb+resource. However, the description does not differentiate this tool from sibling revocation tools like post_tool_gateway_sessions_by_session_id_revoke, lacking explicit 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 use this tool versus alternatives. It only states the operation and authorization class, with no context about prerequisites, when not to use it, or 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?
The description adds the API path and authorization class, which are not in annotations. However, it does not disclose side effects, what happens during restart, or any behavioral traits beyond the basic action. Annotations are minimal, so the description adds some value but not substantial.
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 very short (two sentences) with no wasted words. However, conciseness sacrifices informativeness; more detail could be added without becoming verbose.
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 3 parameters, 2 required, no parameter descriptions, and an output schema not explained, the description provides insufficient context. It does not explain what a gateway runtime slot is, when to restart, or what the result will be.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% with no parameter descriptions in the schema. The description does not explain any parameters (e.g., what companyId or slotId represent, how they affect the restart). This is a critical gap.
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 title and description clearly state the verb 'restart' and resource 'gateway runtime slot'. However, among sibling tools like 'pc_post_tool_gateway_runtime_slots_by_slot_id_stop', the description does not distinguish restart from stop, leaving 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 on when to use this tool versus alternatives like stop or start. No prerequisites or context for usage 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?
Annotations already state readOnlyHint=false (write operation) and destructiveHint=false. The description adds the authorization class 'board_or_agent,' which is a behavioral constraint not present in annotations. However, it does not disclose what creating a session entails (e.g., side effects, TTL behavior, limits on session count). The addition of auth class is notable but incomplete.
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 very short (two sentences) and front-loads the core purpose. It avoids unnecessary detail. However, it could be slightly longer to include parameter semantics without becoming verbose. The conciseness is good but under-informative.
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 (nested input object, 6 properties, 1 required), the description is inadequate. It does not explain the purpose of a tool gateway session, what the output represents, or when creation is needed. With an output schema present but no description of return values, the agent lacks essential context for proper usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the parameters (runId, ttlMs, agentId, etc.). The description mentions none of the input fields, leaving the agent without guidance on what values to provide or their meanings. This is a critical gap for a tool with a nested body object.
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 'Create a tool gateway session' using a specific verb ('Create') and resource ('tool gateway session'). It is unambiguous about the tool's basic function, though it does not explicitly differentiate from related tools like revoke session or other gateway operations.
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, no context about session lifecycle or when creation is appropriate. The only added detail is the authorization class, but no when-to-use or when-not-to-use information.
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 tool is mutable (readOnlyHint=false), idempotent, and non-destructive. The description adds the authorization class ('board') and confirms the actions are 'join' or 'leave'. This provides some additional context but does not significantly expand 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (two sentences), but it lacks structure and detail. It front-loads the action but does not use formatting to highlight key information. While concise, it omits critical parameter guidance.
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, the description does not explain the result of the operation, the meaning of 'starred', or the effect of joining/leaving. For a tool with nested parameters and a clear mutation effect, this omission leaves the agent without enough context to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description offers no explanation of the parameters (state enum, starred boolean, path variables). The agent must infer their meaning solely from the schema structure, which is insufficient.
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 title and description clearly state the tool's action: joining or leaving a project resource. The description includes the HTTP method and path, making the purpose explicit. However, it does not distinguish this tool from similarly named siblings (e.g., the other PUT resource-membership tool), 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 provided on when to use this tool versus alternatives, or on prerequisites such as authorization requirements. The description only restates the tool's function without usage 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 indicate idempotent and not destructive. The description adds the authorization class ('board_or_agent'), but doesn't describe what happens on invocation (e.g., upsert vs create, side effects). It partially complements annotations.
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 short but repeats the title verbatim in the first line, which is redundant. It is structured as two quick sentences, but could be more concise by not duplicating the title.
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 complex nested input, an output schema, and a usage restriction (Summarizer agent only), the description is too sparse. It fails to explain the domain concepts (summary revisions, slots) or provide enough context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about any parameters. Neither the path parameters (companyId, scopeKind, slotKey) nor the body fields (markdown, model, etc.) are explained. This is a critical gap.
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 title and description clearly state it writes a summary revision, and specify the HTTP method and path. The purpose is understandable for someone familiar with the domain, but lacks explanation of 'summary slots' and the meaning of scopeKind/slotKey. It distinguishes from siblings by the specific endpoint.
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 only mentions 'Summarizer built-in agent only' as a constraint. No guidance is provided on when to use this tool versus the GET or POST summary slot tools, nor any prerequisites or context for invocation.
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 idempotentHint: true, destructiveHint: false, and readOnlyHint: false. The description adds authorization context ('board_or_agent') and the HTTP method (PUT), which are useful but do not significantly extend beyond what annotations imply. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence plus operation/auth info), but it is front-loaded with the purpose. However, it lacks structure and does not earn its place with additional useful details. Acceptable but not optimal.
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 an output schema, the description need not explain return values. However, the tool has nested objects, an enum, and required parameters; the description does not explain the behavior of 'mode' or 'allowedAgentIds' or how updates affect existing settings. Lacks essential context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, yet the description does not explain any parameters. The 'mode' enum values (open, allowlist, disabled) and the 'allowedAgentIds' field are left undefined. The description adds no semantic value beyond the schema field names.
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 'Update the current user's inbox agent policy', which clearly identifies the verb (update) and resource (inbox agent policy). The purpose is specific and distinguishable from sibling tools like the GET counterpart, but it does not explicitly differentiate from other update 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 mentions the authorization class but does not explain prerequisites or appropriate scenarios. No explicit when-to-use or when-not-to-use information is 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 idempotent, not read-only, and not destructive. The description adds the HTTP method (PUT) and authorization class 'board_or_agent', which provides some behavioral context beyond annotations. However, it does not disclose details like what fields are required, conflict resolution behavior, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (2 sentences) and front-loaded, but the brevity sacrifices necessary details. While no fluff, it fails to provide enough information for effective use.
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 moderate complexity (2 required nested parameters, output schema exists but unused), the description is incomplete. It doesn't explain what 'upsert' entails, how to specify the document body or key, or what the output looks like. The missing parameter explanations and usage context leave significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%: the description does not explain any parameters. The input schema has nested objects (path, body) with required fields (id, key, format, body) and optional ones (title, changeSummary, baseRevisionId). The description provides zero guidance on how to populate these parameters, making it very hard for an agent to correctly invoke the tool.
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 verb 'Upsert' and the resource 'issue document', and includes the HTTP method and path. However, it does not differentiate this tool from siblings like pc_get_issues_by_id_documents_by_key (read) or pc_delete_issues_by_id_documents_by_key (delete), missing an opportunity to clarify when to use upsert over other document operations.
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 on when to use this tool versus alternatives. The description only states the operation and authorization class, but does not provide context for appropriate usage, such as prerequisites (e.g., issue must exist) 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds the HTTP method (DELETE) and authorization class, which provide some behavioral context. However, it does not describe the consequences (e.g., permanent deletion, cascade effects) or what the response contains. Since the output schema exists, the return value is partially covered, but additional behavioral details are missing.
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 makes it concise. However, it is too brief and sacrifices important context like parameter usage and side effects. The technical note about the Paperclip operation is useful but not essential. Overall, it is adequately concise but could be more informative.
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 destructive nature (destructiveHint=true) and two parameters, the description should provide more context about consequences and parameter details. It does not mention that deletion is permanent, nor does it explain how to obtain the attachmentId. The output schema exists, so return values are covered, but the description lacks enough contextual information for safe and effective use.
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 two parameters: 'body' (optional, no description) and 'path' (required object with 'attachmentId' string, no description in schema). The description does not explain these parameters or their values. With 50% schema description coverage, the description adds no parameter guidance, leaving the agent to infer meaning from the parameter names alone.
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 title and description clearly state the primary purpose: deleting an attachment. The description also specifies the HTTP method and path. However, it does not explicitly distinguish from sibling tools such as pc_get_attachments_by_attachment_id_content or pc_post_companies_by_company_id_issues_by_issue_id_attachments, but since it is the only delete-attachment tool, the purpose is sufficiently 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 mentions authorization class 'board_or_agent', which provides some guidance on who can use the tool. However, there is no guidance on when to use this tool versus alternatives, prerequisites (e.g., needing an attachment ID from another tool), or situations where deletion might be inappropriate. The lack of usage context makes it harder for an AI agent to decide when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds the HTTP method (DELETE) and authorization class (board_or_agent), but does not elaborate on side effects like irreversibility or behavior when the resource does not exist, leaving gaps in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (two sentences) and contains no redundancy. However, it essentially repeats the title and adds endpoint details without a structured breakdown. Acceptably brief but not well-organized.
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 destructive operation on a nested resource, the description lacks context about what a 'skill test input' is, why one might delete it, and what the output implies (though output schema exists). It does not explain the importance of the three path parameters or the consequences of deletion.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 50%, the description should compensate for missing parameter context. It does not describe what each path parameter (companyId, skillId, inputId) represents. The schema properties lack descriptions, and the description adds no semantic value beyond the endpoint pattern.
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 'Delete a skill test input' and provides the endpoint, making the action and resource unambiguous. However, it does not explicitly differentiate from sibling tool pc_delete_companies_by_company_id_skills_by_skill_id which deletes a skill itself, potentially confusing agents.
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, prerequisites (e.g., existing test input), or when not to use it. The description only restates the operation and authorization class.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds the HTTP method (GET) and authorization class (board_or_agent), which provides some context beyond annotations. However, it does not describe pagination, rate limits, or error behaviors.
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) and front-loaded, but the first sentence is redundant with the title. The second sentence adds some technical detail. It is concise but could be more informative without becoming verbose.
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 complexity of the domain (many approval-related sibling tools), the description is incomplete. It does not explain what approvals are, any filtering capabilities, or the output schema (though that exists separately). The agent lacks context to use this tool appropriately.
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 only parameter is path.companyId, which is a required string but lacks any description in either the schema or the tool description. Schema coverage is 0%, and the description adds no additional meaning to this parameter.
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 title and description both state 'List approvals in a company,' clearly indicating the action and resource. However, it does not differentiate from sibling tools like pc_get_approvals_by_id or pc_get_issues_by_id_approvals, which also list approval-related data.
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 the HTTP method and authorization class but offers no guidance on when to use this tool versus alternatives (e.g., pc_get_approvals_by_id). There is no mention of prerequisites, context, 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?
Annotations (readOnlyHint, idempotentHint, destructiveHint) already declare the operation is safe and idempotent. The description adds the authorization class but no further behavioral traits like pagination, scope, or effect. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very short, but the first sentence is clear. However, it lacks structure; the second line about Paperclip operation is not organized for quick parsing. Could be more front-loaded with key info.
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 presence of an output schema, the description's lack of return value explanation is acceptable. However, the tool is simple and the description covers the basic purpose, but missing filtering capabilities and scope (what 'list' means—all examples for a company?). Adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameters. It lists the path template but does not describe query parameters (q, kind, author, project) or their meanings. The agent receives no semantic help for parameter usage.
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?
Title and first line of description clearly state the tool lists decision training examples. However, it does not differentiate from sibling tools that also relate to decision training (e.g., create, delete, patch). The purpose is clear but not uniquely distinguished.
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 on when to use this tool versus alternatives like pc_post_companies_by_company_id_decision_training (create) or pc_delete_decision_training_by_id. It only mentions the HTTP method and authorization class, not context for use.
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 provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds the HTTP method (GET) and authorization class (board_or_agent), which are consistent with annotations. No contradictions. However, the description does not add significant behavioral context beyond what annotations convey, earning a solid 3.
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 lines), which is concise but at the expense of important details like parameter semantics and usage context. It is front-loaded but lacks completeness. Every sentence is present, but more information is needed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list endpoint with one parameter and an output schema, the description provides minimal context: the HTTP path and auth class. It does not explain the concept of inbox dismissals or why one might list them. Given the complexity (simple tool), it is just barely adequate. Output schema existence reduces the need to describe return values, but more would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0% description coverage. The sole parameter (path.companyId) is a string with no description in schema. The tool description does not explain what companyId represents or any constraints. This is a major gap, especially given the low 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?
Title and description clearly state 'List inbox dismissals'. The name and description indicate a GET operation per company. It is distinguishable from siblings like pc_post_companies_by_company_id_inbox_dismissals (create) and pc_delete_companies_by_company_id_inbox_dismissals_by_item_key (delete). However, it lacks elaboration on what an inbox dismissal is, keeping it from a score of 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 explicit guidance on when to use this tool versus alternatives. The description only states the operation without mentioning when to list vs create or delete. Sibling tools exist but no mention of context 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?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds the authorization class ('board') and HTTP method (GET), which are useful but not deeply behavioral. It does not discuss side effects, rate limits, or what happens if no secrets exist.
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 short (two sentences) but repeats the title in the first sentence. It is concise but could be more efficient by combining or adding unique information. The structure is simple and 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?
Given the sensitivity of secrets and the existence of an output schema (not shown here), the description lacks context about what the output contains or how to interpret results. The need for companyId is not explained. The 'board' authorization is mentioned without elaboration.
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 single parameter path.companyId has no description in the schema (0% coverage) and is not explained in the tool description. The agent must infer that a company ID is required from the path template. No guidance on format or meaning.
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 it lists user secret values, with 'my' indicating it's for the authenticated user. Among sibling tools like pc_get_companies_by_company_id_secrets and pc_get_companies_by_company_id_user_secret_definitions, this tool is distinct. However, it could elaborate on what 'user secret values' are.
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 on when to use this tool vs alternatives. The description does not mention any prerequisites, restrictions, or comparisons to siblings like pc_get_companies_by_company_id_secrets. The agent is left to infer from nomenclature.
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, idempotentHint=true. The description adds that it's a GET operation and mentions authorization class. This provides minimal extra context; no disclosure of rate limits, side effects, or what health checks entail.
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) and front-loaded with the purpose, but the second sentence adds technical details that are redundant given the HTTP method is implicit. It is concise but lacks informative content.
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, the description does not explain what the health check returns (e.g., status object, boolean). For a health check tool, the agent needs to know how to interpret the response. The description is insufficient for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain the 'path' parameter or the required 'companyId'. Although the parameter structure is simple, the description adds no semantic value beyond what the schema shows.
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 'Check configured secret providers' and the title matches. It specifies it's a GET endpoint for health status. However, it does not explicitly distinguish from the sibling tool 'pc_get_companies_by_company_id_secret_providers' which likely lists providers, so purpose is clear but sibling differentiation is missing.
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 on when to use this tool versus alternatives like listing secret providers or creating configs. The description only gives technical details (HTTP method, authorization) but does not help the agent decide when a health check 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?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds only the route and auth class, which are already implied by the name and schema, providing minimal additional behavioral context 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 description is very concise with two short sentences. No superfluous content, though it includes technical details (Paperclip operation) that may be extraneous but do not harm clarity.
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 annotations covering safety, the description lacks explanation of what 'impact' means, what the preview returns (no output schema documented), and how the agent should interpret the result. This is incomplete for a preview tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has two required string parameters (companyId, skillId) with 0% description coverage. The description does not explain these parameters, leaving the agent without guidance on what they represent or how to provide them.
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 title 'Preview company skill fork impact' and description explicitly state the tool checks the impact of forking a skill, distinguishing it from the actual fork action (pc_post_companies_by_company_id_skills_by_skill_id_fork) and other skill-related 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 does not provide guidance on when to use this tool versus alternatives (e.g., before forking, or instead of the actual fork). It only mentions authorization class, lacking explicit context for agent decision-making.
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 read-only, non-destructive, idempotent, and open-world hints. The description adds the authorization class 'board_or_agent' and mentions it's a Paperclip GET operation, providing some extra context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two lines), which is concise but too minimal. It lacks substantive information to justify its brevity; every sentence should earn its place, but here it misses key details.
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 only one parameter and an output schema, the description still fails to explain the parameter's meaning or provide usage context. It covers basic operation but leaves significant gaps in understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning the description adds no information about the single parameter (path.companyId). The parameter is not described at all, so the description fails to add 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 title and description both clearly state 'List company skill categories', which is a specific verb-resource combination. It distinguishes from sibling tools like pc_get_companies_by_company_id_skills (which lists skills, not categories), but does not explicitly mention this 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 the HTTP method and authorization class, but fails to specify when to use this tool versus alternatives. No explicit when/when-not guidance or mention of alternative tools like pc_get_skills_catalog.
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 provide readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds authorization class ('board_or_agent') but does not explain what 'refresh' means behaviorally (e.g., whether it changes state). Since annotations carry the burden, a 3 is appropriate—minimal added value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two lines) and front-loaded with the purpose. However, it includes internal implementation details ('Paperclip operation: GET /api/...') that are not useful for the agent. Removing that would improve conciseness. Overall, adequate but not optimized.
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 leaves ambiguity about what 'refresh' entails—whether it modifies state or is purely a read operation. Annotations hint at read-only, but the description's wording could mislead. It lacks prerequisites, return value hints, or context about when a session setup is relevant. The output schema exists but is not referenced, so completeness is lacking.
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 only parameter, sessionId, is documented in the schema but the description adds no meaning beyond what the schema provides. With 0% schema description coverage, the description should compensate but fails to describe the parameter's purpose or format. However, the parameter is simple and obvious from the URI path, mitigating some deficiency.
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 'Get and refresh an environment customImage setup session', which clearly identifies the action (get and refresh) and the resource (custom image setup session by session ID). The verb-resource combination is specific, but it does not explicitly differentiate from sibling tools like create or update, though the verb 'get' implies retrieval.
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 on when to use this tool versus alternatives, such as other custom image session tools (e.g., create, update). The agent receives no context on prerequisites, exclusions, or typical use cases. This is a significant gap given the large sibling list.
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 HTTP method (GET) and authorization class (board_or_agent), which provides some context. However, it does not disclose any further behavioral traits (e.g., rate limits, error scenarios), so it adds modest value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with two sentences, but it omits useful information such as parameter details and usage context. While not verbose, the brevity comes at the cost of completeness.
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 that the tool has one required parameter, an output schema, and is part of a large sibling set related to environment leases, the description is insufficiently complete. It does not describe the return value, the concept of a lease, or any side effects. An agent would have to infer much from the tool name and schema alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The description mentions the endpoint includes {leaseId} but does not explain what a lease ID represents, how to obtain it, or any constraints on the value. This leaves the agent without semantic understanding of the sole parameter.
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 'Get an environment lease', which specifies the verb and resource. The name and title align. However, it does not explicitly differentiate from the sibling tool pc_get_environments_by_id_leases that lists leases for an environment, so while the purpose is clear, it lacks explicit 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?
No guidance is provided on when to use this tool versus alternatives. The description mentions the HTTP endpoint and authorization class but does not specify prerequisites, when not to use it, or how it differs from related tools like pc_get_environments_by_id_leases.
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 (readOnlyHint: true, idempotentHint: true, destructiveHint: false) already convey the safe, read-only nature. The description adds the authorization class but no additional behavioral insights like response size or error scenarios. The annotations carry the burden, and the description adds minimal extra value.
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 concise (two lines) but the first line repeats the title. The second line provides useful technical details. Every sentence is short, but the first could be removed or merged for better efficiency.
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 simplicity (1 param, read-only with good annotations), the description covers the basic purpose. However, it lacks information about the output (response structure) and potential error states. An output schema exists but is not described, leaving the agent to guess the return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain the single required parameter 'id'. The parameter's purpose is implied by the tool name but never explicitly stated. For a 1-parameter tool with no schema descriptions, the description should clarify the parameter's meaning and format.
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 'Get an issue' and includes the API endpoint, indicating it retrieves a single issue by ID. However, it does not explicitly differentiate from similar siblings like pc_get_issues, which lists issues. The distinction is implied by the name and parameter structure.
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 pc_get_issues for listing or pc_patch_issues_by_id for updating. The description only offers technical implementation details (API path, auth class) without usage 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 readOnlyHint=true and destructiveHint=false, making the safety profile clear. The description adds the HTTP method (GET) and authorization class (board_or_agent), which provides some extra behavioral context. However, it omits details like pagination, rate limits, or side effects beyond what annotations cover.
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) and to the point. However, it is too concise, missing crucial parameter explanation. It is not wasteful, but trades completeness 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 the tool is simple (single parameter, output schema present), the description is barely adequate. It fails to explain the parameter or when to use the tool. The presence of an output schema partially compensates for missing return value details, but usage and parameter gaps remain significant.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain the single required parameter `path.id`. The agent must infer that it is the issue ID, but no explicit guidance is given. A good description would state that the parameter is the issue ID whose attachments are to be listed.
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 'List issue attachments' clearly states the verb (List) and resource (issue attachments). The name and title reinforce this. However, it does not explicitly differentiate from siblings like pc_get_issues_by_id or pc_get_issues_by_id_approvals, though the resource name makes it distinct.
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 on when to use this tool versus alternatives (e.g., pc_get_issues_by_id or other attachment operations). No prerequisites (e.g., issue existence) or context 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, idempotentHint, and destructiveHint. The description adds 'Paperclip operation: GET' and 'Authorization class: board_or_agent', which provide additional context but are minor. There is no information about error conditions, return values, or side effects beyond what annotations convey.
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 concise (two sentences) but lacks structure. While brevity is valued, the content is minimal and does not front-load the most critical information. The second sentence about Paperclip operation and auth class is partially redundant with annotations and could be omitted or integrated.
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 is insufficient. It does not clarify what 'heartbeat context' means or what the tool returns. An AI agent would lack sufficient context to understand the tool's role in issue management.
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 0% description coverage for the single parameter 'id'. The description does not explain what 'id' represents (presumably an issue ID). Given the low schema coverage, the description should compensate by describing the parameter, but it fails to do so.
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 the tool's purpose as 'Get issue heartbeat context', which is a specific verb and resource. It also includes the HTTP method and path, adding clarity. However, it does not explicitly differentiate from sibling tools like pc_get_issues_by_id or pc_get_issues_by_id_approvals, and the term 'heartbeat context' is not explained.
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 lacks any context for appropriate usage, exclusions, or references to other tools. An AI agent would have no basis to decide when this tool is preferable.
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 provide readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, which cover behavioral traits. The description does not add extra transparency beyond stating the HTTP method and auth class.
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 concise but lacks substantive content. It repeats the title and adds endpoint details, but fails to include important context.
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 does not explain the typical workflow (e.g., that this is used after calling a test initiation endpoint) or what the status output contains, despite having an output 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 input schema has two required parameters (connectionId and actionRequestId) with no descriptions. The description does not clarify their meaning or provenance, which is insufficient given 0% 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 title and description clearly state getting the status of a tool connection test call, and the description includes the API endpoint and authorization class. However, it does not differentiate this from sibling tools like the one that initiates test calls.
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 on when to use this tool versus alternatives. For instance, there is no mention that this should be used after initiating a test call via another tool.
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?
Description adds minimal insight beyond annotations. It states it's a PATCH operation, which implies mutation, but does not disclose side effects, required permissions beyond 'board', or rate limits. Annotations already indicate it's a readWrite operation.
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?
Description is two sentences long and front-loads the main action. It is efficient but could be improved with bullet points or structured info.
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 tool with nested inputs and many siblings, the description is far too minimal. It does not explain the grants array, role enum, or when to use this over similar patch endpoints. Output schema exists but input behavior is poorly documented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description provides no parameter details despite 0% schema description coverage. The schema has nested objects, arrays, and enums, but none are explained. The description only hints at role and grants without specifics.
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 'Update a company member role and explicit grants', specifying both the resource and the two key aspects. It differentiates from sibling patch member tools which likely don't include grants.
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 on when to use this tool versus others. No prerequisites, context, or exclusions provided. The authorization class note is technical, not usage 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=false and destructiveHint=false, so the description does not need to repeat those. The description adds that authorization class is 'board', which is a useful behavioral constraint. However, it does not disclose other important aspects like whether this is a partial update or full replacement, or error conditions.
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, but it is too sparse for the complexity of the tool. It doesn't waste words, but it fails to provide necessary details, making it under-informative rather than concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complex input schema (nested objects, many fields) and the existence of an output schema, the description is severely incomplete. It does not explain update semantics, prerequisites, or expected outcome, leaving the agent to rely solely on the parameter names.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides zero information about the parameters. The body contains numerous fields including a nested entries array with multiple subfields, but the agent receives no guidance on how to structure these or what values are valid.
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 title and description clearly state 'Update a tool access profile', which is a specific verb-resource combination. The sibling tools include create, delete, and duplicate, so this tool is unambiguously the update 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?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention that the profile must exist or that for creation one should use pc_post_companies_by_company_id_tools_profiles.
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 readOnlyHint=false, idempotentHint=false, destructiveHint=false, but the description adds only the authorization class, not behavioral traits like side effects or error conditions. For a write operation, more disclosure is expected; the description falls short.
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 very concise with two sentences, no wasted words. Purpose is front-loaded. However, the brevity leads to missing details; it could be slightly longer 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?
Although there is an output schema, the description does not mention return values or error responses. The tool has nested parameters and no parameter descriptions, so the description is incomplete for effective use. It fails to provide enough context for an AI agent to use it reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning no parameter descriptions exist in the schema. The description does not explain the 'body' or 'path' parameters (e.g., what the comment body should contain or how to provide the approval ID). This is a critical gap, earning the lowest score.
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 comment to an approval', specifying the verb and resource. The title also reinforces this. However, it does not explicitly distinguish from sibling tools like pc_get_approvals_by_id_comments or pc_post_issues_by_id_comments, earning a 4 rather than 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes the HTTP method and authorization class, which gives some context. However, it lacks explicit guidance on when to use this tool versus alternatives (e.g., commenting on issues) and does not mention preconditions or exclusions. Thus, it is adequate but not comprehensive.
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 adds some behavioral context beyond annotations (HTTP method, endpoint, authorization class). However, it does not disclose side effects like state changes or notifications, which would be useful given the minimal annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two lines) but lacks structured detail. It is not verbose, but the information is sparse and could be better organized for an agent.
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, the description omits important context such as when revision is appropriate, the effect on the approval workflow, and any required preconditions. The nested object parameters are unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description includes no parameter explanations. The description fails to add meaning beyond the schema, such as what 'decisionNote' represents or how 'id' is used.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose ('Request revision on an approval') and adds the HTTP operation and authorization class. However, it does not differentiate from sibling tools like approve, reject, or resubmit, which limits clarity for selection.
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 approve or reject. The description does not specify prerequisites or context for requesting a revision.
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 mutation (readOnlyHint=false) and non-destructiveness. The description adds only the API path and auth class, which adds little beyond what annotations provide. No disclosure of side effects, success behavior, or rate limits.
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 very short (two sentences). It could include more detail without being verbose, but it is front-loaded with the purpose.
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 omits parameter explanations, return value hints, and behavioral context. It is insufficient for an agent to use the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description does not explain any of the three sub-parameters (name, expiresAt, requestedCompanyId). It adds no meaning beyond the schema structure.
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 'Create a named board API key', which is a specific verb and resource. The tool name and title reinforce this. Among sibling tools, it is distinct from other board API key operations like list and delete.
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 on when to use this tool versus alternatives. The description mentions 'Authorization class: board' but does not explain prerequisites, context, 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?
Annotations already indicate a write operation (readOnlyHint false) and non-destructive. The description adds the authorization class ('board_or_agent'), which is helpful. However, it does not disclose other behavioral traits such as side effects, notifications, or state changes beyond schema and annotations.
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 concise with two sentences, but it is under-specified. It front-loads the title and adds a technical line, but it could include more useful context without becoming verbose. The brevity sacrifices informativeness.
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 complexity of the tool (enumerated types, nested objects, output schema), the description is insufficient. It does not explain the types of approvals, their typical use cases, or the response format. The annotations and schema only partially cover the required 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 0%. The description does not explain any parameter semantics, such as the meaning of each approval type (e.g., hire_agent), the payload structure, or the purpose of issueIds. The agent must rely solely on the schema, which lacks descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create an approval' with a specific verb and resource. It also includes the HTTP method and path, indicating it's a company-level operation. However, it does not differentiate from sibling tools like pc_post_issues_by_id_approvals or pc_post_approvals_by_id_approve, which operate on different contexts.
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. There is no mention of prerequisites, when to prefer company-level approval creation over issue-level, or when to use approval actions like approving or rejecting.
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?
Beyond annotations, the description only notes that the upload body is omitted in the source spec and that multipart compatibility is provided. It does not disclose success behavior, error conditions, or any side effects of uploading an image.
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 concise but repeats the title. It front-loads technical details without a clear hierarchy, and the structure could be improved by placing core purpose and usage first.
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, the description does not mention what the response contains (e.g., asset ID). It also omits file format support, size limits, and error handling, leaving the agent with incomplete 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?
The description adds context about the multipart fallback and the omitted upload body, which helps explain the body and multipart parameters. However, it does not explain the path parameter (companyId) or provide full usage details for the multipart structure.
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 uploads an image asset, matching the title. However, it uses jargon like 'Paperclip operation' and does not explicitly distinguish from other upload tools such as pc_post_companies_by_company_id_logo.
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 on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or context for selecting this specific upload endpoint.
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 set destructiveHint=true, so the description need not repeat that. It adds authorization class 'board_or_agent', which is extra context. However, it does not disclose what specifically gets destroyed or any side effects beyond what annotations imply.
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 short and not wasteful, but it omits important information such as parameter meanings and behavioral notes. It could be more informative without becoming verbose.
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 two parameters, a nested object, and a destructive hint, the description is too minimal. It lacks context about prerequisites, output, or the effect of reset, making it inadequate for safe and effective use.
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 50%, and the description adds no parameter details. It does not explain what companyId or key represent, leaving the agent to infer from the path. This is insufficient for a tool with partially documented 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 title and description clearly state the tool resets a built-in agent, and the HTTP path distinguishes it from sibling tools like provision or reconcile. However, it does not explain what 'reset' entails (e.g., restoring defaults or clearing state), which slightly limits 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. Sibling tools like provision, reconcile, and status exist, but no conditions or exclusions are mentioned.
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 traits beyond annotations. 'Preview' implies a read-only operation, but annotations set readOnlyHint=false, creating ambiguity. No side effects, idempotency, or error behavior 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 concise (two sentences) and front-loaded with the core purpose. The second sentence adds technical details that may be less useful but are not excessive.
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 lacks context: no mention of output, prerequisites, or how this preview relates to the broader decision-training workflow. Despite having an output schema, the description adds no completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate, but it provides no information about parameters (sourceKind, sourceId, issueId). The agent gets no hints about their meaning or constraints beyond the schema structure.
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 'Preview a decision training snapshot,' which is a specific verb+resource combination. This distinguishes it from the related 'pc_post_companies_by_company_id_decision_training' tool that creates a snapshot.
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 the create snapshot endpoint. It only includes technical details (paperclip operation, auth class) without explaining the preview's role in the workflow.
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 and destructiveHint=false, but the description adds no behavioral context. It does not disclose side effects, whether the preview creates temporary resources, or any rate limits or permissions beyond the authorization class.
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) but the first sentence simply repeats the title. It is concise but not efficient; the technical details in the second sentence are useful but minimal.
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 that an output schema exists but is not shown, the description does not explain what the preview returns. For a POST operation with side effects allowed (readOnlyHint=false), the description lacks completeness about the operation's behavior and response.
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 50%; the body parameter has a helpful description noting optionality and lack of schema, but the required companyId in path has no description. The tool description does not add further semantics 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 title 'Preview company export' and description repeat the purpose, but the description adds the HTTP method and path, which clarifies the resource. It is distinct from sibling tools like pc_post_companies_by_company_id_exports and pc_post_companies_import_preview, though no explicit comparison is made.
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 on when to use this tool versus alternatives. The description states authorization class but does not provide context for when a preview is useful or when to choose the actual export or import 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 readOnlyHint=false (write operation) and destructiveHint=false. The description adds the HTTP method (POST) and authorization class ('board'), but does not elaborate on side effects (e.g., state changes, notifications) or response 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 short (two sentences) but the second sentence is technical ('Paperclip operation: POST...') and may not be essential for an agent. It could be streamlined to focus on functional utility.
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 that the tool writes to a resource and an output schema exists, the description should at least mention the effect (e.g., request status changes) or what the response represents. It currently lacks this information.
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 description does not explain the parameters (companyId, requestId) beyond their presence in the schema. With schema coverage at 50% and no parameter descriptions in either the schema or the description, the agent gains no additional semantic 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 clearly states the action 'Approve a company join request' with a specific verb and resource. While it does not explicitly differentiate from sibling tools like the GET join requests list or other join request actions, the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as rejecting or listing join requests. The description provides no prerequisites or exclusion criteria, leaving the agent without context for decision-making.
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 provide key behavioral hints (readOnlyHint=false, destructiveHint=false, etc.). The description adds authorization class info ('board_or_agent') and the HTTP method, but does not elaborate on side effects, rate limits, or other behavioral details beyond what is in annotations.
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 concise (two sentences) but at the cost of missing critical information. It is front-loaded with the purpose, but the brevity leaves significant gaps. It could be expanded without becoming overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested objects, required fields, output schema), the description is highly incomplete. It fails to mention the output, required parameters, or any nuances of the creation process. The description alone would not enable an AI agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is complex with many nested objects, but the description provides zero information about parameters. There is no explanation of required fields like 'name' or 'path.companyId', nor any guidance on how to structure the body. Schema description coverage is 0%.
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 'Create a project', which is a specific verb and resource. Among the many sibling tools, this is the only one for creating a project, making it easily distinguishable.
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 guidelines are provided. The description does not mention when to use this tool versus alternatives like pc_patch_projects_by_id or pc_get_projects_by_id. Lacks any context on prerequisites or recommended conditions.
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 readOnlyHint=false and openWorldHint=true, which are consistent with a mutation operation. The description adds the authorization class 'board_or_agent', but does not disclose potential side effects (e.g., overwriting existing catalog skills, required configurations). Some behavioral context is provided beyond annotations, but not enough to fully inform the agent.
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) and front-loaded with the purpose. However, it omits essential details about parameters and usage, making it under-specified. Conciseness is good, but not at the cost of completeness.
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 (nested body, output schema exists but not described), the description is incomplete. It does not explain what the body should contain, what the output represents, or any preconditions (e.g., must have catalog skill ID). This lack of context could lead to misuse.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should explain the body parameter, but it only mentions the path's companyId implicitly. The body is a free-form object with no hints about its structure (e.g., skill identifier, version). This is a significant gap that hinders correct invocation.
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 'Install a catalog skill' with the HTTP method and endpoint, making the purpose understandable. However, it does not differentiate from sibling tools like pc_post_companies_by_company_id_skills, which might also perform installations. A more explicit distinction would improve 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?
No guidance is provided on when to use this tool versus alternatives. It lacks prerequisites, context for when installation is appropriate, and does not mention any alternatives for installing non-catalog skills. This leaves 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?
The description simply states 'Create', which aligns with annotations (readOnlyHint=false), but adds no behavioral details beyond that. No information about authorization requirements, side effects, or what happens on duplicate creation.
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?
Very concise, only two sentences. However, the second sentence ('Paperclip operation... Authorization class: board.') is technical and may not be useful for an AI agent, taking away from clarity.
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 tool with many nested parameters and an output schema (not provided), the description is minimal and incomplete. It does not explain what a 'named MCP gateway' is or how to use the parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention any parameters. It adds no meaning beyond the input schema, failing to compensate for the lack of documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create a named MCP gateway.' This is a specific verb and resource, distinguishing it from sibling tools like pc_get_companies_by_company_id_tools_gateways and pc_patch_tool_gateway_gateways_by_gateway_id.
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 on when to use this tool versus alternatives. Does not mention prerequisites, conditions, or when to create vs get or patch.
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, destructiveHint=false, etc., but the description adds no extra behavioral context (e.g., what reconciliation entails, side effects). It meets the baseline with annotations but does not enrich understanding.
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, which is concise but at the expense of necessary detail. It lacks substance beyond the title, making it borderline under-specified.
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 complexity (nested objects, oneOf modes) and the lack of parameter descriptions, the description is insufficient for an agent to correctly invoke the tool. Output schema exists but does not compensate for missing 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 0%, and the description omits any explanation of the complex input schema (body modes: forward, override, quarantine_restore; reason field). This is a significant gap for an agent selecting modes.
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 ('Reconcile') and resource ('execution workspace branch record'), providing a specific verb+resource combination. However, it does not differentiate from sibling tools like pc_patch_execution_workspaces_by_id, which may also modify the workspace.
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 there any prerequisites or context about the reconciliation process. The description lacks situational cues.
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 mutation (readOnlyHint=false) and non-destructive nature (destructiveHint=false). The description adds no behavioral details beyond stating the operation and auth class. It doesn't mention side effects (e.g., if replays overwrite something), authorization requirements in practice, or rate limits. The contribution over annotations 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short: one line for purpose, one for operation and auth class. It is front-loaded and efficient. The extra line adds operational context without waste. Could be considered slightly under-specified but not verbose.
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, the description does not mention return values, success/error conditions, or what 'create or replay' means in practice. The tool has nested parameters and multiple fields, but no guidance on their relationships. The openWorldHint suggests extensibility but does not substitute for basic completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate but provides no information about parameters. The 'path' and 'body' parameters, including 'token', 'requestType', 'agentName', and others, are entirely unexplained. The agent cannot understand what values to supply or their purpose from the description alone.
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 'Accept an invite and create or replay a join request', which is a specific action on a specific resource. The title reinforces this. Among sibling tools, it uniquely handles invite acceptance versus viewing (pc_get_invites_by_token) or revoking (pc_post_invites_by_invite_id_revoke), providing clear 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 offers no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., having a valid invite token), when acceptance creates versus replays a request, or when to prefer other invite-related tools. The agent is left to infer usage 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 indicate readOnlyHint=false (write operation) and openWorldHint=true (possible side effects). The description adds the 'Authorization class: board_or_agent' detail, which is useful beyond annotations. However, it does not elaborate on side effects like notifications or state changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but at the expense of omitting critical parameter and usage information. While it is front-loaded with the purpose, it lacks necessary detail, making it under-specification rather than 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 the tool's complexity (2 required params, deeply nested body schema, open world hint), the description is severely incomplete. It does not explain return values (output schema exists), role of parameters, or behavioral nuances. An output schema exists but is not described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about parameters (e.g., that 'body' is required, nested structure, or meaning of fields like 'reopen', 'metadata'). The agent must infer entirely from the schema, which is complex.
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 comment to an issue,' which is a specific verb and resource. Among sibling tools like pc_get_issues_by_id_comments and pc_delete_issues_by_id_comments_by_comment_id, this tool's purpose is uniquely identified.
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., when to add vs. retrieve or delete comments). Prerequisites like issue existence or user permissions are not 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 already indicate non-readonly, non-idempotent, non-destructive. The description adds the HTTP method and authorization class but no additional behavioral traits. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (two sentences) but lacks necessary context. It is not wasteful, but it is under-informative.
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 two required nested parameters and no explanation of their purpose, the description is incomplete for the tool's complexity. An output schema exists but does not compensate for missing parameter semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning the description provides no parameter details. The schema itself documents claimSecret and requestId constraints, but the description adds no semantics about their role or usage.
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 title and description clearly state the tool claims an API key for an approved join request. However, no differentiation from sibling join-request tools is provided.
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 on when to use this tool versus alternatives, nor any preconditions (e.g., request must be approved). The description simply restates 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?
Annotations already mark the tool as destructive (destructiveHint=true). The description adds only the HTTP method and authorization class, but does not elaborate on side effects, irreversibility, or what exactly gets deleted (e.g., associated models).
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 short and includes key details (HTTP method, path, authorization), but sacrifices completeness for brevity. It could be restructured to include more relevant context without adding length.
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 tool is destructive, has an output schema, and multiple parameters, yet the description lacks critical context such as what the output contains, potential restrictions, or data impacted. It feels incomplete for a delete 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 description does not explain the 'type' parameter beyond being in the path, and the body parameter is only described as an 'optional compatibility payload' in the schema. Schema coverage is 50% (body has description, type does not), and the description adds no further meaning.
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 'Delete' and the resource 'adapter', specifies the HTTP method and path, and contrasts with sibling tools like get/patch adapters. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., patch vs delete), prerequisites, or consequences. The description omits contextual usage instructions.
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?
Beyond the annotations (destructiveHint=true, idempotentHint=true), the description adds that the operation uses DELETE and requires 'board_or_agent' authorization. This is useful but still minimal. It does not mention what happens on success, failure modes, or side effects like cascading deletions.
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 very concise, with two sentences front-loading the purpose and then adding the endpoint and auth class. However, it lacks structure (e.g., bullet points or separate sections) and could include more detail without bloat.
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 a nested path object and an output schema (not referenced), the description is incomplete. It does not explain what the output contains, nor does it provide enough context for a destructive operation (e.g., irreversibility, prerequisite checks). The agent may lack confidence in using this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no meaning beyond the input schema for the parameters. The 'body' parameter has a note about being optional and lacking a schema, but the 'path' parameters (companyId, folderId) are not described. With schema coverage at 50%, the description should compensate, but it does not.
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 title 'Delete a folder' combined with the description specifying the DELETE endpoint makes the verb and resource clear. It distinguishes itself from sibling tools like pc_delete_companies_by_company_id (delete a company) and other delete tools by focusing on a specific resource (folders). However, the description does not explain what a 'folder' represents in this context, so it is not 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 does not provide any guidance on when to use this tool versus alternatives (e.g., moving items out of a folder first, or using another tool like pc_delete_companies_by_company_id). No prerequisites or conditions are mentioned. The agent is left to infer usage context without support.
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 destructiveHint=true and readOnlyHint=false. The description adds authorization class 'board_or_agent' and confirms it's a DELETE operation, providing some behavioral context beyond annotations. However, it lacks details on side effects (e.g., cascading deletes) or irreversibility.
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 very short—two sentences—and front-loaded with the core purpose. However, it is too minimal, sacrificing useful detail for brevity. Every sentence earns its place, but more context could be added without becoming verbose.
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 complexity (destructive operation with nested parameters and an output schema), the description is incomplete. It does not explain return values, consequences of deletion, or confirm the operation's scope. Annotations partially compensate, but the description should provide more behavioral and postcondition 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 50%; the body parameter has a description explaining it's an optional compatibility payload, but the path parameters (companyId, skillId, runId) have no descriptions. The tool description does not add any parameter semantics or usage hints 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 'Delete a skill test run' which is a specific verb and resource. It differentiates from sibling tools like pc_delete_companies_by_company_id_skills_by_skill_id (delete a skill) by specifying 'test run' in the title, though it doesn't explicitly distinguish from similar delete tools for test-related resources.
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 deleting a skill or test inputs. It only states the HTTP method and authorization class, but no context about prerequisites or typical use cases.
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 flag destructiveHint=true and idempotentHint=true. The description adds the authorization class ('board'), which is useful context about who can perform this action. However, it does not disclose other behavioral traits like irreversibility, consequences of deletion, or subsequent effects on related resources.
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 notably concise (two sentences) and presents the core purpose first. However, it lacks a structured break between general purpose and technical specifics, though this is acceptable for a simple operation.
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 destructive nature, the description should clarify the deletion's scope and any side effects. It only mentions the HTTP operation and authorization, leaving gaps about return values (despite an output schema existing) and operational impact. Annotations help but are insufficient.
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 2 parameters (body and path) with only 50% schema description coverage. The description does not explain what companyId, policyId, or body represent, forcing the agent to infer from the tool name. This is inadequate for proper parameter comprehension.
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 title and description clearly state the tool deletes a tool policy, and specify the HTTP method and path. However, the description does not differentiate this from other delete or policy tools among the many siblings, missing an opportunity to clarify its specific role.
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 (e.g., other delete tools or policy update tools). It does not mention prerequisites, when not to use it, or what to do before calling it.
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, idempotentHint=true, and readOnlyHint=false. The description adds that the HTTP method is DELETE and that authorization class is 'board_or_agent', which adds context beyond annotations. However, it does not disclose any side effects, such as whether the deletion cascades or affects other data.
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 very short (two sentences) and to the point, with no superfluous content. It could be improved by adding more context without becoming verbose.
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, the description does not mention what the tool returns. It lacks usage context, parameter details, and behavioral nuance. Given the many sibling tools, this minimal description may lead to confusion.
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 50%, and the description adds no explanation of the parameters. The 'path.id' is implied by the URL but not described, and the optional 'body' parameter is not clarified on when it should be used.
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 title and description clearly state the verb ('Delete') and the resource ('a decision training example'), making the purpose unambiguous. However, it does not differentiate from sibling tools like pc_patch_decision_training_by_id or pc_get_decision_training_by_id, which also operate on the same resource.
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 prerequisites or conditions for use. For a delete operation, it is expected to at least note that the example must exist and that deletion is irreversible, but this is 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?
Annotations already set destructiveHint: true, so the description should disclose additional behavioral traits beyond that. The description only restates the HTTP method and authorization, adding no new information about side effects, irreversibility, or data impacts. This is a missed opportunity to 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with only two sentences, but it lacks necessary detail. While it is front-loaded with the purpose, the brevity results in under-specification. The structure is minimal but efficient, though not optimally informative.
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 that there is an output schema, the description does not need to explain return values. However, for a destructive operation, more context is needed: what happens to associated resources, whether the operation is reversible, or any constraints. The description fails to provide a complete picture for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema coverage at 50%, the description should clarify the parameters. However, it does not explain the 'labelId' or 'body' parameters beyond what the schema already provides. The description adds no value to the agent's understanding of how to use these 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 clearly states 'Delete a label', which is a specific verb and resource. The tool name 'pc_delete_labels_by_label_id' aligns with this purpose, and among sibling tools like 'pc_get_companies_by_company_id_labels' and 'pc_post_companies_by_company_id_labels', it is distinct as the delete 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?
The description provides no explicit guidance on when to use this tool vs alternatives. It mentions the HTTP method and authorization class but does not specify prerequisites, such as needing an existing label ID, or contraindications. Without this, the agent lacks context for proper invocation.
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 convey that the tool is destructive and idempotent. The description adds the HTTP method and authorization class (board_or_agent), which provides useful behavioral context. However, it does not disclose any additional traits beyond what annotations imply, such as the scope of deletion (e.g., whether it cascades).
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 (two sentences) and front-loads the primary purpose ('Delete a secret'). The additional technical details (HTTP method, auth class) are relevant but not excessive. It could be improved by including parameter information without adding much length.
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 omits critical context about the deletion's effects, such as whether it is irreversible, what happens to references, or if there are any constraints (e.g., cannot delete secrets in use). The description is insufficient for an agent to safely execute this operation without external knowledge.
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 description does not mention any parameters or explain their purpose. The input schema has 50% coverage (path.id is required but lacks a description; body is optional with no schema). Without parameter context in the description, the agent cannot infer how to construct the `id` value or differentiate required vs optional 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 starts with 'Delete a secret', which clearly states the action and resource. However, it does not differentiate from sibling delete operations for other entities (e.g., agents, issues) or from other secret operations like patch or rotate, leaving the agent to rely on the tool name alone 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 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 specify prerequisites, contexts where deletion is appropriate, or scenarios to avoid. The mention of authorization class is a requirement, not usage 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 indicate destructiveHint=true and idempotentHint=true. The description adds 'Authorization class: board', providing useful context about permissions. However, it doesn't elaborate on irreversible nature or cascading effects beyond what annotations imply.
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 concise with two front-loaded sentences. It includes the API endpoint and authorization class without fluff. Could be slightly more informative while remaining 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 destructive operation, the description lacks completeness. It does not mention what happens after deletion, whether the operation is reversible, or any confirmation steps. Even with an output schema, more behavioral context 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?
The description does not add meaning beyond the input schema. Schema description coverage is 50% (body parameter lacks description, path.applicationId only has type). No extra guidance on how to use parameters or their constraints.
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 'Delete a tool application', which clearly specifies the verb and resource. It distinguishes from sibling tools like pc_delete_companies_by_company_id by focusing on tool applications. However, it could briefly clarify what a tool application is.
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 on when to use this tool versus alternatives, no prerequisites or consequences mentioned. For a destructive operation, this is a significant gap.
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. The description adds the HTTP method (GET) and authorization class (board_or_agent), which provides some context beyond annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences with no wasted words. Everything present is relevant.
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, the description is incomplete: it fails to document the required input parameter and does not differentiate from related tools. The minimal context leaves important gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must explain parameters, but it does not. The only parameter (path.id) is not described, leaving the agent unaware that it needs an agent ID.
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 title and description 'List agent skills' clearly state the action and resource. However, it does not differentiate from sibling tools like pc_get_skills_index, which lists skills globally, but the purpose is still 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?
No guidance on when to use this tool versus alternatives (e.g., pc_get_skills_index for global skills, pc_get_agents_by_id for agent details). No when-not-to-use or prerequisite information.
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 provide readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds the HTTP method and authorization class, which are not in annotations, but does not disclose behavioral traits like rate limits or data freshness.
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 short but includes a redundant title line that echoes the title. It could be more concise by combining the first two lines. The structure is front-loaded but not optimally efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input (one parameter) and existence of an output schema, the description provides the basic operation but lacks completeness in explaining the purpose and usage context. It does not mention how to obtain the approval ID or the expected response shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'id' parameter or its expected format. The tool requires a path object with an id string, but no semantic context is provided to help the agent construct a valid input.
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 'Get an approval' and specifies the HTTP method and path. However, it does not differentiate from sibling tools like pc_get_companies_by_company_id_approvals or pc_get_approvals_by_id_issues, which could cause confusion about the exact scope.
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 on when to use this tool versus alternatives. It does not mention expected context, prerequisites, or situations where other tools would be more appropriate. The description simply states the operation and authorization class.
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 safety profile is clear. Description adds authorization class and endpoint details. However, it does not disclose error conditions, expected content type, or size limitations. With strong annotations, the description adds moderate value.
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?
Description is very concise (three lines) with front-loaded purpose. However, there is an empty line that could be removed for efficiency. Every sentence earns its place, but the brevity sacrifices completeness.
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 (mentioned in context), the description is incomplete. It lacks details on error handling, content type, size limits, and prerequisite steps. For a tool with one parameter and no schema descriptions, the agent needs more context to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'attachmentId' parameter. It fails to add meaning beyond the schema structure, such as how to obtain the ID or what format it should be. The agent must infer from context.
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?
Title 'Download attachment content' and description clearly state the tool's purpose: downloading attachment content. It specifies the HTTP method and authorization class. It distinguishes from siblings like pc_get_issues_by_id_attachments (list) and pc_delete_attachments_by_attachment_id (delete). However, it could be more specific about the returned content type.
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 on when to use this tool versus alternatives. It does not explain prerequisites (e.g., needing an attachment ID from a list operation) or when not to use it. Siblings like pc_get_issues_by_id_attachments 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds only the HTTP method and API path; annotations already declare readOnlyHint true, idempotentHint true, destructiveHint false. No additional behavioral context (e.g., pagination, filtering, or what a 'connection' represents).
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 sentences with no extraneous information. However, the brevity omits important parameter details, making it less effective.
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 output schema exists and annotations are rich, the description covers the basic purpose but lacks parameter semantics and usage context. For a simple read tool with one param, it is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and description does not explain the meaning or purpose of the required 'companyId' parameter. The agent must infer from parameter name alone.
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 verb 'List' and resource 'cloud upstream connections'. It is distinct from sibling cloud upstream tools (e.g., connect, push).
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 on when to use this tool vs alternatives (e.g., pc_post_cloud_upstreams_connect_start). No context about prerequisites or typical use cases.
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, covering safety. The description adds that it uses GET and requires board_or_agent authorization. This is minimal but consistent. It does not disclose pagination, ordering, or content of the activity list, which would be valuable.
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 very concise with three sentences, front-loaded with the essential purpose. No unnecessary words. However, it could include more helpful context (e.g., parameter info) 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?
Given the tool's simplicity (one parameter, read-only, output schema exists), the description together with annotations and schema provides a minimal but functional set of information. However, the lack of parameter semantics and usage guidance leaves gaps that could hinder correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage and the description provides no information about the 'companyId' parameter. The agent must rely on the parameter name and nested structure. With no param details in the description, this is a significant gap.
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 title 'List company activity' and description clearly state the verb (list) and resource (company activity). However, it does not differentiate from sibling tools like pc_get_companies_by_company_id_timeline or the POST version pc_post_companies_by_company_id_activity, which may also deal with activity listings. The description provides the API route and authorization class, adding context but not clarifying scope.
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. Siblings include both a GET and POST activity tool, as well as timeline tools, but the description offers no explicit context or exclusions. The agent must infer usage from the name and endpoint.
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, idempotentHint, etc. Description adds the HTTP method and authorization class, but does not elaborate on behavioral aspects like pagination or output format.
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 concise (two sentences), but it omits important context such as the output schema or usage notes. The brevity borders on underspecification.
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 presence of an output schema and many sibling tools, the description is too minimal. It does not mention what the output contains, nor any filtering or pagination behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required parameter (companyId) with 0% documentation coverage, and the description does not explain its meaning or constraints. The description fails to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists agents in a company, using a specific verb and resource. It distinguishes from siblings like 'pc_get_companies_by_company_id' which lists companies, not agents.
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 on when to use this tool versus alternatives. Many sibling tools relate to agents (e.g., pc_get_agents_me, pc_get_companies_by_company_id_built_in_agents), but no differentiation 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, destructiveHint, idempotentHint, and openWorldHint, covering most behavioral traits. Description adds authorization class 'board_or_agent' and technical details (HTTP method, path), which adds some value but is not substantial.
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?
Description is concise (two lines) but the first line repeats the title verbatim. The technical detail in the second line is useful but could be integrated more efficiently.
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 an output schema, the description does not need to explain return values, but it lacks any context about what 'provisioning state' means or what the listing includes. The description is incomplete for a tool with no parameter documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no parameter information beyond what is in the schema. The description does not explain the companyId parameter or its format.
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 explicitly states 'List built-in agent provisioning state', using a specific verb and resource. It clearly distinguishes from sibling tools that perform actions like reconcile, provision, or reset.
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 on when to use this tool vs alternatives. Does not mention when-not or provide context for selection among related built-in agent 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 read-only and non-destructive. The description adds the HTTP method and authorization class, which are useful. No additional behavioral traits (e.g., pagination, limits) are disclosed.
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 only two sentences and is front-loaded with the title. It is concise with no unnecessary words. Could be slightly more structured, but meets the standard.
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 presence of many similar cost tools and an output schema, the description lacks completeness. It does not explain the output format, what 'kind' means, or how it differs from other finance reports.
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 only parameter is companyId, which has no description in the schema. The description does not explain what companyId is. The nested path object may also be confusing. The parameter semantics are not clarified.
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 it is a cost report by financial kind, and includes the HTTP method and path. The title and first sentence match. However, the term 'kind' is not defined, which could be ambiguous among similar cost 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 other cost report tools (e.g., costs_summary, costs_by_biller). No prerequisites or context are given.
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 read-only, idempotent, and not destructive. The description adds the authorization class ('board_or_agent'), which provides useful security context beyond the annotations. However, it does not mention any other behavioral traits.
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 with only two sentences, front-loading the title and operation. It is concise with no wasted words, but it sacrifices completeness 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 the tool has one parameter and an output schema, the description lacks context about the report content, when to use it, and how it relates to other cost tools. The presence of an output schema reduces the need to explain return values, but the description is still too sparse to be fully useful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description does not describe the single parameter (path.companyId) at all. While the tool name implies the parameter's purpose, the description fails to add any semantic meaning beyond what the schema provides.
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 states "Cost report: finance-summary" and the HTTP method, indicating it retrieves a finance summary costs report for a company. However, it does not explain what the report contains or how it differs from sibling cost tools like pc_get_companies_by_company_id_costs_summary, leaving 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 on when to use this tool versus alternatives among the many cost-related sibling tools. The agent is left to infer usage context without explicit when-to or when-not-to 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it is a GET operation and requires 'board_or_agent' authorization, which is valuable behavioral context beyond annotations. However, it does not describe the response behavior or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences), but the first sentence repeats the title ('Get dashboard data') unnecessarily, making it somewhat tautological. The second sentence adds useful info. Could be more concise by removing the first sentence.
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?
While annotations cover behavioral aspects, the description fails to describe the output (dashboard data) or parameter semantics. For a retrieval tool with an output schema, the description should summarize what data is returned. It lacks completeness for an agent to fully understand the tool's effect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 1 parameter (path with companyId) with no descriptions (0% coverage). The description does not explain the parameter's purpose or format. The agent receives no help in understanding what companyId means.
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?
Clear verb ('Get') and resource ('dashboard data') is stated, but no differentiation from sibling tools like pc_get_companies_by_company_id which also retrieve company data. The description identifies the specific endpoint and authorization, aiding purpose 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?
No guidance on when to use this tool versus alternatives. The description mentions authorization class but does not specify context or exclusions. Sibling tools exist for similar company data, but no differentiation is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds the HTTP method (GET) and authorization class ('board'), which are behavioral traits beyond the annotations. This provides useful context about how the operation interacts with the system, though it could further describe side effects or pagination.
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 (three sentences) but repeats the title verbatim. While it is concise, it could be more efficient by removing redundancy and integrating parameter details. The structure front-loads the purpose but omits essential information.
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 low complexity (single parameter, output schema exists), the description is incomplete. It fails to explain the companyId parameter, which is critical for correct invocation. The presence of an output schema reduces the need to describe return values, but the parameter gap makes the description inadequate for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one required parameter (path with companyId), but the description offers no explanation of what companyId represents or how to obtain it. With 0% schema description coverage, the description fails to compensate, leaving the parameter semantics entirely undefined for 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 states 'List company invites' as both title and description, identifying the verb (list) and resource (company invites). It additionally specifies the HTTP method and endpoint, which clarifies the operation. However, it does not differentiate itself from sibling list operations for other resources, limiting 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?
The description provides no guidance on when to use this tool versus alternatives. It lacks any context for invocation, prerequisites, or exclusions, leaving the agent without decision support for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, establishing safety and idempotency. The description adds the authorization class 'board_or_agent' and the HTTP method GET, providing some behavioral context beyond annotations. However, no further traits like pagination, rate limits, or side effects are disclosed.
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 short (two sentences) and front-loaded with purpose. However, it is under-informative for the tool's needs, omitting parameter details and response expectations. While not verbose, it sacrifices completeness 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 the tool has an output schema and nested objects, the description could be more complete by mentioning the nature of the response or any defaults. It does not address that it returns all projects or any filtering. The openWorldHint suggests large output, but no pagination context is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter 'companyId' in the input schema has 0% description coverage, and the description does not explain what it represents or how to obtain it. With no compensation from the description, the agent lacks the necessary context to correctly provide this parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The title and description clearly state 'List projects in a company', providing a specific verb and resource. Among sibling tools like pc_get_projects_by_id (single project) and pc_post_companies_by_company_id_projects (create), this tool is uniquely positioned as the listing endpoint, 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 does not provide any guidance on when to use this tool versus alternatives. It lacks prerequisites, when-not-to-use context, or differentiation from sibling tools for project operations. Only the authorization class is mentioned, which is not usage 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 provide readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds authorization class ('board_or_agent'), which is helpful. However, it does not disclose other behavioral traits like rate limits, pagination, or what the secrets list contains.
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 concise (two sentences) and front-loaded with the purpose. The second sentence adds relevant operation and auth details without unnecessary fluff. A small improvement would be to merge the first sentence with the title 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 an output schema, so return values need not be described. However, the description lacks parameter semantics and usage guidelines, making it barely adequate for the agent to correctly invoke the tool. The annotations compensate somewhat, but the description could be more helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not explain the 'companyId' parameter beyond its implicit presence in the path. The agent receives no guidance on what companyId represents or how to determine its 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 title and description clearly state the tool lists secrets in a company. The description clarifies it's a GET operation to /api/companies/{companyId}/secrets. However, it does not specify what constitutes a 'secret' in this context, which leaves some ambiguity for the agent.
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 vs alternatives (e.g., creating or updating secrets, listing secrets for the current agent). No context or exclusions are given, forcing the agent to rely on sibling tool names 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?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds the authorization class ('board_or_agent') and confirms it is a GET operation. This provides some behavioral context beyond annotations, but still lacks details on side effects or data scope.
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 very short (two sentences), front-loading the title and endpoint. It is efficient but could pack more useful information without increasing length significantly.
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 omits context about what 'skill update status' entails and when this endpoint is relevant. However, since an output schema exists, the return values do not need explanation. The description is minimally adequate but leaves the agent guessing about the tool's role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameters. It only lists the endpoint path without describing what companyId and skillId represent or how they are used. The agent receives no semantic help beyond property names.
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 'Get skill update status' and specifies the HTTP GET endpoint, clearly indicating the action and resource. However, it does not differentiate from sibling skill tools like pc_get_companies_by_company_id_skills_by_skill_id, leaving the exact meaning of 'update status' ambiguous.
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 prerequisites, typical scenarios, or exclusions, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds the authorization class ('board_or_agent'), which is useful. However, it does not disclose pagination, ordering, or what 'dated' revisions entails, leaving gaps beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at two lines, but it is unstructured, mixing a one-line summary with an HTTP endpoint. It could benefit from separation of purpose, parameters, and behavior. No wasted words, but minimal value added.
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 existence of multiple siblings and an output schema, the description provides only the core action and endpoint. It does not explain the concept of summary slots, what 'dated revisions' means, or how results are filtered/sorted. The authorization class is helpful but insufficient for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameter semantics. The URL pattern implies 'companyId', 'scopeKind', and 'slotKey' but provides no definition or context for these fields. The description fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'dated revisions for a summary slot', making the action unambiguous. It distinguishes from sibling tools that likely list slots themselves (pc_get_companies_by_company_id_summary_slots_by_scope_41be68b525) or modify slots.
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 on when to use this tool versus other summary slot tools (e.g., put, post, or list slots). The description only provides the HTTP endpoint and authorization class, but no context about prerequisites, ordering, or typical use cases.
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 tool as read-only and idempotent. The description adds the HTTP method and authorization class, which provides some additional context but does not significantly expand on behavioral traits 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 extremely concise with two sentences, each adding value: the first restates the purpose, and the second provides the HTTP method and authorization. No wasted words.
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, the description is too minimal for the complex context of over 200 sibling tools. It does not explain what 'installed catalog teams' are or how the tool fits into the broader workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the meaning or format of the required 'companyId' parameter. It fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List installed catalog teams', which is a specific verb-resource pairing. However, it does not differentiate this tool from sibling tools like pc_get_teams_catalog, which may retrieve similar data.
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 scenarios for 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds 'Authorization class: board' providing auth context, but does not disclose other behaviors like error handling or pagination. With annotations, the bar is lower; description adds minimal value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. Purpose is front-loaded. Every word is relevant. Could not be more concise while retaining meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (tool name is long but operation is simple), output schema exists, and annotations are good, the description is bare-bones. It lacks context about the response or the nature of 'governed tool decisions', but the output schema fills some gaps. Adequate but minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% (no descriptions in schema). The description does not explain the parameters (companyId, runId) beyond implying them via the URL path. It fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get governed tool decisions for a run transcript' which includes a specific verb and resource. It also mentions the HTTP method and path. However, the term 'governed tool decisions' is not explained, and the description does not differentiate from other 'get' operations for runs like pc_get_heartbeat_runs_by_run_id_issues.
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 on when to use this tool vs. alternatives. The description provides only the HTTP method and authorization class, without specifying conditions for use 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 declare readOnlyHint=true, destructiveHint=false. The description adds only the HTTP method (GET) and authorization class ('board'), but fails to disclose pagination, filtering, or error behaviors. Minimal additional value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: one for purpose, one for technical details. No redundant information. Every sentence 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 an output schema, the description omits what the list returns (e.g., template names, IDs). No mention of pagination or approval status. With only one parameter, it should provide more context on the returned data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single required parameter 'path.companyId' is not described. With 0% schema description coverage, the description must explain the parameter's meaning but merely implies it via the URL template. The agent cannot infer that companyId is the company identifier.
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 'List approved stdio MCP templates' with a specific verb and resource. It distinguishes from sibling POST tools that create templates. The title reinforces the purpose.
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 on when to use this tool versus alternatives like the POST version for creating templates or other list tools. No usage context or prerequisites 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 already declare readOnlyHint, idempotentHint, destructiveHint. Description adds the HTTP method GET and authorization class 'board_or_agent', providing some extra behavioral context, but does not elaborate on implications or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two lines: a one-sentence purpose and the operation details. No unnecessary information, though parameter descriptions could be added 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 tool has an output schema, so return values are not needed in the description. However, the description lacks explanation of what an 'inbox agent policy' is, which may be important for understanding the tool's purpose. Basic completeness is achieved but with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the meaning of companyId or userId beyond their presence in the URL template. For a nested object parameter, this is insufficient guidance.
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 verb 'Get' and the resource 'a company user's inbox agent policy', specifying the context of company and user. It distinguishes from the sibling tool for the current user's policy by explicitly mentioning companyId and userId.
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 the 'me' version or other policy tools. There is no mention of prerequisites, when-not-to-use, or context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds the HTTP method (GET) and authorization class (board_or_agent), which are useful but expected. It does not disclose error handling or edge cases. With good annotations, the description provides minimal additional value.
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: 3 sentences, front-loaded with the purpose, and includes relevant technical details. No wasted words.
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 fails to explain the input parameter 'id' and does not provide context on when to use this tool. For a simple one-parameter tool, the description should cover parameter semantics and usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the 'id' parameter. However, it only references the path template without clarifying that 'id' is the workspace ID. The agent is left guessing what value to provide. This is a critical gap.
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 'Check close-readiness of a workspace', which is a specific verb and resource. It distinguishes itself from sibling tools (no other close-readiness tool), but does not explain what close-readiness means, leaving some 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 on when to use this tool versus other workspace-related tools like pc_get_execution_workspaces_by_id or pc_patch_execution_workspaces_by_id. The description lacks prerequisites, when-not-to-use, or alternative suggestions.
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 read-only, idempotent, non-destructive. The description adds authorization class (board_or_agent) and HTTP method, providing some extra behavioral context. However, it does not describe what the output contains or any other behavioral traits.
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 directly states the purpose, HTTP method, and authorization class. It is front-loaded with the essential information, with no unnecessary 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?
Given the annotations (safe operation) and presence of an output schema, the description covers the basic function. However, it lacks parameter documentation and usage guidance, leaving the agent to guess how to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter (path.id) with no description, and schema coverage is 0%. The description does not explain what 'id' refers to (execution workspace ID), leaving the agent to infer its meaning from the tool name.
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 title 'List workspace operations' and description repeat the same phrase, clearly indicating the tool lists operations for a workspace. However, the description does not differentiate this tool from siblings like pc_get_heartbeat_runs_by_run_id_workspace_operations, which also lists workspace operations but for a different context.
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 on when to use this tool vs alternatives. The description only states what it does, without any context about prerequisites, when it is appropriate, or when to prefer other 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 declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe, non-destructive operation. The description adds the endpoint path and authorization class, which provides some additional context. However, it does not explain any behavioral aspects like whether the token is validated or what happens on invalid token.
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 very concise with only two sentences, both directly relevant. The first sentence states the purpose, and the second provides technical details (endpoint and auth). No unnecessary information is included.
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 presence of an output schema, the description does not need to detail return values. However, with only one required parameter and no description of it, the tool lacks completeness. The context of 'onboarding data' could be expanded to indicate its role in the invite flow (e.g., used during acceptance).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one required parameter (path.token) with no description coverage. The tool description does not mention this parameter at all, failing to add any meaning beyond the schema definition. The agent is left without understanding what the token is or how to obtain it.
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 retrieves onboarding data for an invite, using the verb 'Get'. However, it does not distinguish it from the sibling tool pc_get_invites_by_token, which also retrieves invite information but not onboarding-specific data. A bit more specificity would clarify the unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 pc_get_invites_by_token or other invite-related tools. The description mentions authorization class is public, but does not explain prerequisites or the typical workflow context (e.g., during invite acceptance).
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 readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds the HTTP method and authorization class, which provides extra context beyond annotations, but doesn't detail what 'activity' includes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no unnecessary information. Every sentence is substantive, making it highly 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?
Despite having an output schema, the description lacks details about the response content, pagination, or activity types. Given the tool's context among many issue-related tools, it is incomplete for an agent to fully understand outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one required parameter (path.id) with 0% description coverage. The description does not mention or explain this parameter, leaving the agent without guidance on how to use it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists activity for an issue, with specific verb and resource. While it doesn't explicitly differentiate from sibling tools like comments or approvals, the name and title are unambiguous, and the HTTP path is given.
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 on when to use this tool versus alternatives (e.g., pc_get_issues_by_id_comments for comments). No context on prerequisites or scenarios.
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. The description adds the authorization class 'board_or_agent,' which is useful context beyond annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded with the purpose. However, it is too minimal, missing important information like parameter meaning and usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with annotations covering safety and output schema existing, the description is minimally adequate. However, it lacks parameter explanation and usage context, which could be provided in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain the sole parameter 'path.id,' leaving the agent unaware that it represents the issue ID. The description fails to compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Title and description clearly state 'List issue comments,' indicating a specific verb and resource. The name distinguishes it from siblings like pc_post_issues_by_id_comments and pc_get_issues_by_id_comments_by_comment_id, but the description does not explicitly differentiate them.
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 on when to use this tool versus alternatives. The description only provides technical details (API path, auth class) without context on appropriate usage or conditions.
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, idempotentHint, and destructiveHint. The description adds the HTTP method and authorization class, but lacks details on pagination, filtering, or response structure. Since output schema exists, the agent can infer return format, but the description could provide more 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 very concise, consisting of two short sentences. It front-loads the core purpose and adds technical details. However, it could be slightly more informative without sacrificing 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 the tool's simplicity and the presence of annotations and output schema, the description is weakly complete. It does not explain what issue documents are, nor does it mention any filtering or ordering capabilities. The agent may need to rely on output schema to understand the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the single parameter 'id'. It is implied to be an issue ID from context, but this is not explicit. The description fails to add 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 title and description clearly state that the tool lists issue documents. The verb 'List' and resource 'issue documents' are unambiguous. However, it does not distinguish itself from sibling document operations like get by key or put.
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., pc_get_issues_by_id_documents_by_key). No exclusions or context about prerequisites 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?
Annotations already declare readOnlyHint, idempotentHint, etc. The description adds only that it's a GET operation and the required auth. This provides minimal extra behavioral context, such as what exactly is returned or any side effects, which are already covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at three sentences, with the main purpose front-loaded. However, it lacks structured sections (e.g., behavior, parameters, returns), but its brevity is generally appropriate.
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 (which reduces the need to explain returns), the description omits details like pagination, what constitutes an 'external object', or error conditions. For a list operation, this information is missing, leaving the tool's behavior partially undefined.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain the single parameter (path.id). No format, example, or guidance is given. The description adds no value beyond the raw schema, which is insufficient for an 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 title and description clearly state the tool lists external objects mentioned by an issue. The verb 'list' and resource 'external objects' are specific. However, it does not differentiate from sibling tools like pc_get_issues_by_id_external_object_summary, leaving room for confusion.
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 mentions the HTTP method (GET) and authorization class (board_or_agent), providing some usage context. But it gives no guidance on when to use this tool versus alternatives (e.g., summary or refresh endpoints), making usage guidelines 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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds the authorization class ('board_or_agent') and the exact API endpoint, which gives some behavioral context beyond annotations. However, it does not disclose error handling, pagination, or rate limits.
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 concise: two sentences that front-load the purpose and include the HTTP operation and authorization. Every sentence adds value, though it omits parameter details. It is efficient but could be more informative without being verbose.
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 a nested input schema and an output schema, the description is too minimal. It does not explain what 'runs' are, how the output is structured, or any behaviors like filtering or ordering. The output schema exists but the description should clarify the tool's role among many siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should explain the parameters. It does not describe the 'path' object or the 'id' field. The tool name and title imply the 'id' is an issue ID, but the description provides no explicit documentation, relying solely on the schema structure.
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 'List runs for an issue', which is a specific verb and resource. The tool name includes 'issues_by_id', so the purpose is evident. However, it lacks explicit differentiation from other list-runs tools like pc_get_routines_by_id_runs, but the 'for an issue' wording 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?
No guidance is given on when to use this tool versus alternatives. It mentions the HTTP method and authorization class, but does not specify context, prerequisites, or scenarios where this tool is preferred over similar 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 declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds the authorization class (board_or_agent) and the HTTP method, providing some additional behavioral context, but does not disclose other traits like error handling or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, consisting of two short sentences. It front-loads the core action and immediately provides the operation details. However, it could be slightly more informative without adding length.
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 that an output schema exists, the description need not cover return values, but it lacks context about what 'tree control state' represents and when agents should use this tool. It minimally meets requirements but is incomplete for a user unfamiliar with the domain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description should explain parameters, but it only indirectly implies the 'id' parameter via the URL path. It does not explicitly describe the required 'path' object or the 'id' field, leaving room for confusion.
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 title and description state 'Get issue tree control state', clearly indicating the verb and resource. It distinguishes itself from sibling issue tools by specifying 'tree control state', though it does not elaborate on what that entails.
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 the HTTP method and path, and authorization class, but gives no guidance on when to use this tool versus alternatives, nor any context for 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 provide readOnlyHint, idempotentHint, destructiveHint. The description adds the API path and authorization class, which gives some context but does not elaborate on behavior (e.g., empty list, error handling). The added value beyond annotations is moderate.
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: two sentences. The purpose is front-loaded. The second sentence contains technical details (API path, auth class) that are not strictly necessary but are not wasteful. It is 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 simplicity of the tool (one parameter, list operation) and presence of output schema, the description is minimally complete but lacks explanation of what 'tree holds' are and the output format. It does not guide the agent on the concept or expected result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not explain the 'path' parameter or the 'id' field. The schema shows a nested object with required 'id', but no description clarifies that 'id' is the issue ID. The description adds no value for 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 'List issue tree holds', which is a specific verb ('list') and resource ('issue tree holds'). It distinguishes from sibling tools (create, get specific, release) by implying a listing operation, though it does not explicitly differentiate.
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 on when to use this tool vs alternatives (e.g., pc_post_issues_by_id_tree_holds, pc_get_issues_by_id_tree_holds_by_hold_id). Does not state that this is for reading all holds vs other operations.
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. The description adds the HTTP method (GET) and authorization class (board_or_agent), which provide some additional behavioral context. However, it does not describe the response format or any potential side effects beyond what annotations convey.
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 sentences front-loaded with the title. Every sentence adds value (purpose, HTTP method, auth class). 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?
For a simple read operation with strong annotations and an existing output schema, the description is minimally adequate. However, it lacks explanation of what a 'watchdog' is or any details about the response structure, which could be helpful for an agent unfamiliar with the domain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description does not explain the 'path' parameter or its sub-field 'id' (likely the issue ID). With no schema documentation and no compensatory explanation in the description, the agent has no guidance on parameter 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 'Get active issue watchdog' as the purpose, using a specific verb and resource. It distinguishes from sibling tools like pc_put_issues_by_id_watchdog and pc_delete_issues_by_id_watchdog by implying a read operation. The HTTP GET method is also provided for 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 such as pc_put_issues_by_id_watchdog or pc_delete_issues_by_id_watchdog. There is no mention of 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?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, indicating a safe read operation. The description adds the HTTP method and authorization class ('board'), providing minor behavioral context beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the purpose. It contains no unnecessary words. However, 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.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex domain with many plugin-related sibling tools and only one parameter, the description is too minimal. It does not explain what a plugin is, what the response contains (though output schema exists), or any prerequisites. More context is needed for an AI agent to use this tool appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions are provided in the schema. The description does not explain the parameters either (e.g., what 'pluginId' is or how to obtain it). The schema is clear but lacks textual guidance.
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 'Get a plugin' and specifies the HTTP method and path. It is clear that the tool retrieves a single plugin by ID, but it does not differentiate from sibling tools like pc_get_plugins (list all plugins) or other plugin-specific 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 vs alternatives (e.g., pc_get_plugins for listing, pc_get_plugins_tools for tools within a plugin). The description lacks explicit context for 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, indicating safe read behavior. The description adds the HTTP method and authorization class ('board'), which provides some context but does not elaborate on potential error conditions or rate limits.
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 very concise (two lines). It front-loads the purpose. However, it sacrifices informativeness 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 that an output schema exists, the description does not need to explain return values. However, it fails to describe what kind of logs are retrieved (e.g., runtime, audit) and whether any filtering is possible, leaving ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% parameter description coverage. The description does not explain the 'pluginId' parameter, its expected format, or its purpose. This leaves the agent with no guidance on how to correctly fill the parameter.
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 'Get plugin logs' provides a clear verb and resource. The tool name similarly indicates retrieving logs for a specific plugin. However, it does not distinguish from sibling tools like pc_get_plugins_by_plugin_id_health or pc_get_plugins_by_plugin_id_jobs.
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 like other plugin-related tools. There is no mention of prerequisites, contexts, or filters.
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, openWorldHint=true, destructiveHint=false. The description adds authorization class but no further behavioral context beyond what annotations provide. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is very short (three lines) with no extraneous text, but it sacrifices needed parameter explanation. It is efficient but not sufficiently informative.
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 complexity (many siblings, one parameter, output schema present), the description lacks detail about the return value and what a routine is. It does not compensate for the sparse parameter schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter 'path' with nested 'id' string, but the description does not explain what 'id' refers to (e.g., routine ID). With 0% schema description coverage, this omission makes parameter semantics unclear.
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 'Get a routine' which is clear and specific. It adds HTTP method and path, and authorization class, providing exact action. Sibling tools include other routine operations (post, patch, delete, get_runs) so this tool is distinct.
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 on when to use this tool versus alternatives like pc_patch_routines_by_id or pc_get_routines_by_id_runs. The description does not mention prerequisites or context for choosing this tool.
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, idempotentHint, and destructiveHint, covering safety. The description adds the HTTP method and endpoint, but does not disclose any additional behavioral traits such as what 'usage' data includes or any side effects. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, consisting of two sentences. While it is concise, it is too brief and lacks substantive information beyond the title and a technical detail. It is not optimally structured for agent use.
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 input (one parameter) and the presence of an output schema, the description does not need to explain return values. However, it lacks context about what 'usage' means in the domain and how this tool relates to sibling secret tools, making it incomplete for an agent to fully understand its role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain the only parameter 'path.id'. The meaning of 'id' is implied but not stated, leaving the agent without explicit semantics. The description fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get secret usage', which is a specific verb ('get') and resource ('secret usage'). This clearly identifies the tool's purpose and distinguishes it from other secret tools by the 'usage' aspect, though it doesn't elaborate on what usage entails.
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 mentions 'Authorization class: board' but does not explain usage context or mention any alternatives, leaving the agent without clear selection criteria.
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, destructiveHint=false, so the safety profile is clear. The description adds 'Authorization class: board_or_agent', which provides useful context about who can invoke it. However, it does not disclose other behaviors like response format or error conditions.
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 very concise, using only three lines to state the purpose, HTTP method, and authorization class. There is no unnecessary text. However, it could be slightly expanded to include parameter details without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, return value details are not needed. However, the description lacks explanation of what a 'catalog skill' is and how this tool fits into the broader skills API. With many siblings, the agent would benefit from a note about its specific use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds no information about the parameters. The single required parameter 'catalogId' is not explained. The agent must infer its meaning from the URL path in the description, which is insufficient for proper use.
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 'Get a catalog skill' clearly indicates the action and resource. The name and title make it obvious this retrieves a single catalog skill by ID, distinguishing it from similar tools like pc_get_skills_catalog (likely listing) and pc_get_skills_catalog_by_catalog_id_files (files). However, the description itself does not explicitly differentiate among siblings.
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 on when to use this tool versus alternatives. It mentions the HTTP method and authorization class, but fails to specify that this is for retrieving a specific catalog skill by ID as opposed to listing all or searching. The agent is left inferring 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.
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. The description adds authorization class 'board_or_agent' and the HTTP method/path, which provide some behavioral context but do not significantly extend beyond what annotations imply.
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 concise, consisting of two short sentences. However, the first sentence 'Get skills index' is extremely terse and could be more informative. Overall, it is efficient but slightly under-specified.
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 existence of an output schema, the description does not need to detail return values. However, it lacks context about what the skills index contains (e.g., a list, a summary) and how it fits among many skills-related siblings. 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?
The input schema has no parameters, so schema coverage is 100% trivially. The description does not need to add parameter information, but it also provides no additional semantic value about parameters. Baseline score of 3 is appropriate.
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 title and description state 'Get skills index' but do not explain what an 'index' means or how it differs from other skills-related tools like pc_get_skills_available or pc_get_skills_by_skill_name. The verb and resource are clear, but the scope is vague.
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. The agent receives no hints about when this is the appropriate choice among many sibling 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the HTTP method (GET) and authorization class, but does not explain what 'agents available' means or provide further behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise, two sentences. The second sentence provides exact API endpoint and authorization. No unnecessary text, though the first sentence repeats the title.
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 an output schema present, the description does not need to explain return values. However, it lacks prerequisites, usage context, and does not clarify what 'agents available' means. Minimal but acceptable for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description adds no information about the only parameter (connectionId). The agent gets no guidance on what a valid connectionId looks like or how to obtain it.
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 'List agents available for tool connection test calls' with a specific verb and resource. It distinguishes itself from a sibling like pc_post_tool_connections_by_connection_id_test_calls by focusing on listing rather than executing calls. However, it does not explicitly differentiate from all siblings.
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 on when to use this tool versus alternatives, such as before making test calls or to check available agents. Sibling tools exist for related tasks, but context is missing.
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, idempotentHint, and nondestructive, so the safety profile is clear. The description adds the HTTP method and authorization class. However, it does not disclose what the response contains or any side effects (though likely none). 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (three lines) but repetition occurs: the first line duplicates the title. It is under-specified for a tool with many siblings and an undocumented parameter. While not verbose, it sacrifices essential detail for brevity.
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 returns do not need detailed explanation. However, given the large number of sibling tools and the vague term 'usage', more context is needed (e.g., what usage data is retrieved, typical values). The description is adequate but not complete for an agent unfamiliar with the API.
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 one required parameter (path.connectionId) with no description. Schema description coverage is 0%, so the description must compensate. It mentions the endpoint includes {connectionId} but does not explain what connectionId is or its format. This fails to add meaning beyond the raw 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 states the verb 'Get' and the resource 'tool connection usage' clearly. It specifies the HTTP endpoint and authorization class, making the basic purpose understandable. However, it does not define what 'usage' encompasses (e.g., counts, logs, summary), leaving some ambiguity. It also does not differentiate from sibling tools like pc_get_tool_connections_by_connection_id_activity.
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. There are many sibling tools for tool connections (e.g., getting the connection itself, activity, grants), but no context for choosing this one. The description lacks both explicit when-to-use and when-not-to-use information.
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 readOnlyHint=false, indicating mutation and potential destruction. The description adds no additional behavioral context beyond the title, failing to explain what pausing/resuming entails or side effects. Since annotations exist, the bar is lower, but the description still contributes negligibly.
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?
Two sentences; the first unnecessarily repeats the title. The structure is tolerable but not optimal—the operation line is useful but could be integrated. Slightly more verbose than needed.
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?
Two required parameters with nested objects, no parameter descriptions, and no examples. The output schema exists but is not described. For a mutation tool flagged as destructive, the description lacks critical context about the override concept and the effect of pausing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (description does not explain parameters). The 'paused' boolean and 'type' string are not described—the agent must guess that 'paused: true' means pause. No added meaning beyond the raw schema types.
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 ('Pause or resume') and the resource ('an adapter's override of a builtin'). It distinctly differentiates from sibling tools like pc_patch_adapters_by_type (general update) and pc_delete_adapters_by_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 mentions the HTTP operation and authorization class but provides no guidance on when to use this tool versus alternatives (e.g., when to pause vs resume, or when to use the non-override patch tool). No explicit when-to-use or when-not-to-use information.
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-idempotent and non-destructive nature. Description adds auth class 'board_or_agent', which is useful. However, does not disclose that path can be set to null or whether the update is partial.
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?
Very short, two sentences. The second sentence on HTTP method and auth class is arguably not essential but does not waste much space. Could be improved by replacing with parameter context.
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 nested parameters and no schema descriptions, the description is insufficient. Missing parameter explanations and usage context, though an output schema exists (not shown).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description must explain parameters. It fails to describe body.path, adapterConfigKey, or path.id, leaving the agent to infer from the schema structure.
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 title and first sentence 'Update agent instructions path' clearly state the action and resource. However, no distinction from sibling tools like pc_patch_agents_by_id_instructions_bundle, which could cause 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 on when to use this tool versus alternatives, no prerequisites, and no mention of expected effect. Only technical details (HTTP method, auth class) are 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 indicate readOnlyHint=false and destructiveHint=false. The description adds the HTTP method and authorization class, but does not disclose behavioral traits like whether updates are partial replacements or full merges. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences are concise, but the second sentence (internal endpoint reference) adds little value for an AI agent. The description is not verbose, but it fails to use its space effectively.
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 an output schema existing, the description omits critical context: this modifies the current user's profile, name is required, image can be a URL or empty, and it likely does a partial update (PATCH). This leaves the agent with significant ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description provides no explanation of the 'body' parameter or its subfields (name, image). The agent must rely solely on the schema names, which lack context like format or 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 'Update current user profile', specifying the verb (update) and resource (current user profile). It distinguishes itself from sibling tools that target other entities (e.g., agents, issues).
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 on when to use this tool versus alternatives like pc_get_auth_profile (read) or other update tools. The description lacks context about prerequisites, side effects, or comparison with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate write (readOnlyHint=false), non-destructive, non-idempotent. The description adds the authorization class and HTTP method, providing some context beyond annotations. However, it does not disclose side effects, required permissions, or behavior related to openWorldHint=true.
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 (three lines) and front-loaded with the title. However, it lacks informative content beyond technical details, making it minimally acceptable.
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 complexity (nested objects, 0% schema coverage), the description does not explain parameters, response, or PATCH semantics. It omits crucial context like notification of partial update and ignores openWorldHint implications.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about parameters (body with name, brandColor, etc., path with companyId). The agent must rely solely on the schema, which is insufficient for understanding 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 'Update company branding' and provides the HTTP method and path, making the tool's purpose unambiguous. It is specific about the resource (branding) and distinguishes from sibling tools like pc_patch_companies_by_company_id which update company info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives or prerequisites. The description only includes technical details (HTTP method, path, auth class) without any when-to-use or when-not-to-use 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 indicate readOnlyHint=false and destructiveHint=false, so the description adds minimal behavioral context. It mentions 'Authorization class: board' and that it's a PATCH operation, which is consistent. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with one sentence and a note about the operation. It is efficiently structured with no wasted words, but could benefit from more detail while remaining brief.
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 complexity of nested parameters with enums and the presence of an output schema (not shown), the description is insufficient. It does not explain required fields, effects of updating status/role, or return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so descriptions must compensate. The description only says 'update status or role', which hints at the body parameters but does not explain the enum values or that membershipRole can be null. The schema provides some constraints, but the description adds little meaning beyond field names.
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 'Update a company member status or role', which is a specific verb+resource. However, it does not differentiate from sibling tools like pc_patch_companies_by_company_id_members_by_member_id_0357ace8e7 and _4669d5971d, which likely perform similar updates.
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, prerequisites, or when not to use it. The description lacks explicit usage 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 indicate readOnlyHint=false and destructiveHint=false, so the description's mention of update is consistent. It adds the authorization class 'board_or_agent', which is useful, but does not disclose patch semantics or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, front-loading the purpose. However, it omits critical guidance, making it under-specified, but still structured appropriately.
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 2 parameters (nested objects) and no schema descriptions, the description is incomplete. It does not explain the return value (output schema exists but unused) or the full scope of the update 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 coverage is 0% (no parameter descriptions in the schema). The description does not elaborate on any parameters, leaving the agent without guidance on what the body fields (name, description, body) mean or how to use them.
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 'Update a skill test-run template' which clearly identifies the verb (update) and resource (skill test-run template). It distinguishes from sibling tools that create, list, or delete templates, though it could more explicitly contrast with create.
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 creating, listing, or deleting templates. The description lacks context on prerequisites (e.g., needing the templateId) and when not to use this 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 provide readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the safety profile is clear. The description adds the authorization class, which is useful extra context. However, it does not detail behavior like status transitions or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, front-loading the purpose. However, it omits parameter details, which slightly reduces its efficiency. Still, it is well-structured and free of fluff.
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 nested input schema and the existence of sibling tools for annotation threads, the description is incomplete. It does not explain that the status field has an enum or how this PATCH differs from other endpoints like POST for creating replies. The output schema exists but is not referenced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does not mention any parameters, leaving the agent to rely only on the schema. The description adds no semantic meaning beyond the schema's structure.
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 verb 'Update' and the resource 'routine description annotation thread'. It also provides the HTTP method and path, which aids understanding. However, it does not differentiate from sibling tools like the POST endpoint for adding replies, 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 like the POST endpoint for creating threads or adding replies. The description does not include any usage context 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 destructiveHint=true. The description adds the HTTP method and authorization class but does not disclose side effects (e.g., whether the change is reversible, what happens to the user's permissions), impact on other systems, or error conditions.
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 concise with three sentences, no superfluous text. It front-loads the purpose and includes technical details (HTTP method, path, authorization class) efficiently.
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 tool is a destructive admin operation, but the description lacks important context such as what 'demoting' entails, whether the action is reversible, required permissions, and typical use cases. The output schema exists but does not compensate for missing behavioral 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 50%. The description does not explain the 'body' or 'path.userId' parameters. While the schema provides property names and types, the description adds no additional meaning or usage context for the 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 clearly states the action 'Demote a user from instance admin', using a specific verb and resource, and it distinguishes from the sibling tool pc_post_admin_users_by_user_id_promote_instance_admin which performs the opposite action.
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 when the user should be demoted, what prerequisites exist (e.g., user must currently be an instance admin), or when it might be inappropriate to 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 indicate readOnlyHint=false (mutation) and destructiveHint=false (non-destructive). The description adds no behavioral details beyond stating the operation and authorization class, leaving side effects and prerequisites unclear.
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 concise with two sentences. The first sentence states the purpose, and the second provides technical details. No redundancy, but it could be slightly more structured for clarity.
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 operation's complexity (admin promotion), the description lacks details about effects, prerequisites (e.g., user existence, caller permissions), error cases, or output. The presence of an output schema mitigates the need for return value explanation, but overall completeness is low.
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 50%, but the description does not elaborate on parameters. The 'body' parameter is vaguely described as 'Optional JSON compatibility payload' in the schema, and the description adds no further meaning. With low coverage, the description should compensate, but it does not.
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 ('Promote a user to instance admin') using a specific verb and resource. It distinguishes from the sibling tool 'pc_post_admin_users_by_user_id_demote_instance_admin' which presumably demotes, so the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., demote). The description mentions authorization class but does not specify prerequisites, context, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the authorization class 'board_or_agent' beyond annotations. However, it does not explain behavior changes (e.g., starting a run, state transitions) that complement 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 description is very short with three lines, no redundant details. It is concise but could benefit from structured bullet points for parameters.
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 existence of many sibling lifecycle operations, the description lacks context on agent state requirements and relationship to other tools. Output schema exists, but absence of use-case guidance makes it 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?
The description provides no parameter information. Schema coverage is 50% (body has a weak description from schema), but the description fails to add any meaning or usage context for the 'id' parameter.
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 'Resume an agent' with a verb and resource. However, it does not differentiate this from similar lifecycle operations like 'wakeup' or 'pause', which are present among siblings.
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., pc_post_agents_by_id_wakeup, pc_post_agents_by_id_pause). No prerequisites or state requirements 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?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds the HTTP method and authorization class, which is useful but does not expand on the behavioral effects of cancellation (e.g., whether the run is irreversibly stopped). 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one line plus a technical note), but it sacrifices completeness. It is well-structured but lacks key information.
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 presence of nested parameters and an output schema, the description is incomplete. It does not explain the effect of cancellation, what happens to the push run, or what the response contains. The output schema exists but is not leveraged.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It fails to describe what connectionId, runId, or companyId represent, adding no 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 clearly states the action 'Cancel a cloud upstream push run', with a specific verb and resource. It distinguishes from sibling tools like preview, push, and get operations.
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 vs alternatives, no prerequisites, and no exclusions. It merely repeats the tool's purpose without 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 declare readOnlyHint=false and destructiveHint=false, so the description adds value by stating the authorization class (board_or_agent). However, it does not disclose whether creation triggers side effects (e.g., agent initialization) or what happens after creation.
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 very short (two sentences) and front-loaded with the purpose. It is concise but at the cost of completeness; every sentence earns its place, but it could be more informative without being verbose.
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 high complexity (many nested parameters, output schema present), the description is too brief. It does not summarize key fields or the overall effect of the operation. The output schema exists, so return values are covered, but the description lacks completeness for the input side.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description adds no explanation of the many complex parameters (e.g., permissions, runtimeConfig, instructionsBundle). The schema is self-documenting to some extent, but the description fails to provide any semantic context beyond what is in the JSON 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 creates an agent, with the verb 'Create' and resource 'agent'. It does not differentiate from other agent creation tools among siblings (e.g., pc_post_companies_by_company_id_agent_hires), but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It only mentions the authorization class. There is no 'when-to-use' or 'when-not-to-use' context, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, destructiveHint=false. The description adds the authorization class 'board_or_agent', which is useful. However, it does not disclose other behavioral traits like what happens to child folders or required permissions beyond the class. Overall, minimal addition beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded with the purpose. It is efficient but at the cost of completeness. Still, it earns a 4 for being concise and to the point.
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 complexity of the tool (2 parameters with nested structures, required fields, output schema exists), the description is too sparse. It does not explain behavior, return value, or differentiate from related tools. With an output schema present, some information is assumed, but the description still lacks essential 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 0%, so the description must compensate, but it does not explain any parameter. Parameter names are somewhat self-explanatory (companyId, folderId, parentId, position), but the absence of descriptions for required and optional fields (e.g., what parentId does, how position works) leaves the agent without crucial context.
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 title and description clearly state 'Move or reorder a folder', and the name includes 'move'. The purpose is specific and understandable. However, it does not differentiate from siblings like pc_post_companies_by_company_id_folders_items_move, which might also involve moving. Still, it is clear enough.
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 prerequisites, exclusions, or context are provided. With many sibling tools, this is a significant omission.
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 minimal behavioral context beyond annotations. Annotations already indicate readOnlyHint=false and destructiveHint=false, so the agent knows it's a non-destructive mutation. The term 'Preview' suggests a simulation, but the description does not explain what happens on execution, whether it creates a job, or what the output represents.
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 short (two sentences) but not optimally structured. The first sentence provides purpose, but the second mixes technical details (Paperclip operation) with auth class. It is concise but lacks front-loading of actionable information for an agent.
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 (previewing a company import) and the presence of an output schema, the description should explain what the preview returns or how to interpret results. It does not, leaving the agent without context on the output or side effects. The description is incomplete for effective use.
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 50% (body has a placeholder description but no schema; path companyId lacks description). The description does not add meaning beyond the schema. With coverage at 50%, the description should compensate, but it only restates the operation path and auth class.
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 'Preview company import', which is a specific verb-resource combination. It distinguishes from siblings like pc_post_companies_by_company_id_imports_apply (apply import) and other import-related tools by clearly indicating this is a preview 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?
The description provides no guidance on when to use this tool vs alternatives. It does not mention prerequisites, typical scenarios, or when not to use it. The auth class 'board_or_agent' is included but adds no usage 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 indicate the tool is not read-only or destructive (readOnlyHint: false, destructiveHint: false). The description adds the authorization class and HTTP method, but does not disclose other behavioral traits such as side effects or rate limits. The bar is lowered due to annotations, so score 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but includes redundant information (Paperclip operation path) that could be omitted. It does not earn each sentence; the first line is sufficient, and the second line 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?
The description lacks explanation of the difference between dismiss and snooze, or what conditions warrant each. While an output schema exists, the tool's behavior and decision-making context are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameters. The agent must rely solely on the schema for parameter meaning, which is insufficient for a 2-parameter tool with nested objects.
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 ('Create') and the resource ('inbox dismissal or snooze'), with a distinct purpose compared to sibling tools for getting or deleting inbox dismissals.
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 dismiss vs snooze, or when to use GET/DELETE variants. The description only states the operation and authorization class without contextual usage advice.
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 destructiveHint=true and readOnlyHint=false. The description adds the authorization class ('board') and the HTTP method, providing some additional context. However, it does not explain consequences like notifications or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences; the first repeats the title but is still clear. The second provides useful operational context (HTTP path and auth class). Generally concise with no superfluous text.
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?
Missing prerequisites (e.g., requires 'board' authorization interpreted) and behavioral details (e.g., what happens after rejection). With an output schema, return values are covered, but the description lacks sufficient context for an agent to use it confidently.
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 description does not add any parameter semantics beyond the input schema. The schema has 50% coverage: 'body' has a description, but path properties (companyId, requestId) lack descriptions. The description could clarify what these IDs represent but does not.
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 title and description state 'Reject a company join request' clearly, specifying the action and resource. However, it does not differentiate from sibling tools like 'pc_post_companies_by_company_id_join_requests_by_requ_6177e7bc63' (likely approve).
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 on when to use this tool versus alternatives like approve or cancel. The description only provides the HTTP operation and authorization class but lacks context for decision-making.
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 readOnlyHint=false (mutating) and destructiveHint=false. The description adds the HTTP method (POST) and authorization class ('board_or_agent'), which are useful behavioral details not present in annotations. However, it does not describe side effects, error cases, or response behavior, though the output schema may cover the latter.
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), but the first sentence repeats the title. It is not bloated, but it fails to earn its space by omitting important parameter guidance. A 3 is appropriate for minimalistic but not wasteful.
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 (many body parameters, nested objects, output schema), the description is severely incomplete. It does not explain required fields, typical usage patterns, or relationships to other skill operations. For a creation endpoint, more context is needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%: the description does not mention any parameters at all. With 14+ optional fields plus a required 'name' and path 'companyId', the description adds no meaning beyond the raw schema. An AI agent receives no guidance on what fields are important or how to compose the request.
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 'Create a company skill', which clearly indicates the verb (create) and resource (company skill). This distinguishes it from sibling tools that list, get, patch, or delete skills. However, it does not explicitly differentiate from related creation tools like imports or scans, so it is not a perfect 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 use this tool versus alternatives. It does not mention prerequisites (e.g., company ID must exist), nor does it suggest using get/patch/delete for other operations. The only extra information is the authorization class, which is more behavioral than usage guidance.
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 minimal behavioral context beyond annotations. It states the HTTP method (POST) and authorization class, but does not explain what cancellation entails (e.g., does it stop a running run? Can it be undone?). Annotations already indicate destructiveHint=true, so the description 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 extremely concise: three short sentences covering purpose, operation, and authorization. No unnecessary words, front-loaded with the core action.
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 destructive operation, the description lacks critical context: what happens when a test run is cancelled? Is it reversible? What is the expected output? Output schema exists but is not referenced. The description does not provide enough for an agent to use it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain any of the parameters (companyId, skillId, runId, body). The schema provides no descriptions for path properties, and the body description is vague. With 50% schema coverage, the description should compensate but fails to do so.
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 'Cancel a skill test run', which is a specific verb+resource combination. It distinguishes itself from sibling tools like delete test runs, as cancel and delete are different operations. The inclusion of the full API path reinforces the action.
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 (e.g., delete test run, get test runs). It does not mention prerequisites, such as the test run being in a cancellable state, 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 indicate non-readOnly and non-idempotent, but description provides only the authorization class. No disclosure of side effects, permissions beyond auth class, or what 'install' entails.
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?
Very concise, two lines. Front-loaded with action. No wasted text, but could benefit from more structure for clarity.
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 output schema and nested params, description lacks context about behavior, return values, or error conditions. Too minimal for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (body described, path properties not). Description adds no parameter semantics beyond schema. Baseline 3 as coverage is moderate.
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?
Title and first line clearly state 'Install catalog team', which is a specific verb-resource combination. However, it does not differentiate from sibling tools like `pc_post_companies_by_company_id_skills_install_catalog`.
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 on when to use this tool versus alternatives, no prerequisites or context provided. The description only states the operation and authorization class.
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 (destructiveHint=false, etc.) already indicate it's not destructive. The description adds the HTTP method and auth class, but doesn't clarify what 'preview' entails (e.g., side effects, simulation, return structure). The additional context is minimal, so a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (two sentences) and front-loaded with the title. While it could include more useful information, it wastes no words. However, the structure could be improved by grouping related information.
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 (POST with required path params, optional body, output schema), the description is too minimal. It omits the purpose of previewing, expected output, and important behavioral context. The presence of an output schema reduces but does not eliminate the need for explanation.
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 50%, and the description adds no parameter information. The 'body' parameter is noted as optional with no schema, but path parameters (companyId, catalogId) are not described. The description fails to compensate for low 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 'Preview catalog team install' with the HTTP method and path, indicating a preview operation. However, it does not distinguish this from sibling tools like the actual install operation or other catalog-related tools, so it's clear but lacks 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 use this tool versus alternatives (e.g., when to preview vs. actually install). It only mentions authorization class, which is more about prerequisites than usage 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 disclose readOnlyHint=false (write) and destructiveHint=false. The description adds 'Authorization class: board', which hints at permissions but doesn't elaborate on side effects (e.g., whether the action request is consumed or remains). 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two sentences) and front-loaded with the primary purpose. The second line adds operational details (endpoint, auth class) that may be useful but are not strictly necessary. Overall efficient, though could be more informative without added length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex input schema (2 required params, nested objects with many fields) and the presence of an output schema, the description fails to explain what the tool does beyond a high-level operation. The agent cannot infer how to structure requests from this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not mention any parameters. The input schema is complex with many nested fields (name, scope, selectors, etc.), leaving the agent with no guidance on what values to provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Create), resource (tool trust rule), and source (from an action request). This distinguishes it from other trust-rule creation tools that may create rules directly, as evidenced by sibling 'pc_post_companies_by_company_id_tools_trust_rules_by_f4c99894c7'.
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 context about action request lifecycle. It simply states what it does, leaving the agent without decision-making support.
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 provide readOnlyHint=false, destructiveHint=false, but the description adds minimal behavioral context. It says 'roll back' implying a state change, but does not clarify if the operation is reversible, what happens to the current template, or any side effects. Beyond annotations, the description adds little transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences. The first sentence clearly states the purpose. The second provides useful technical context (API endpoint and authorization). However, it is slightly terse and could benefit from a bit more detail without becoming verbose.
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 complexity (rollback operation, required path parameter, optional query and body) and the richness of sibling tools, the description is incomplete. It does not mention the output schema, explain the rollback behavior, or specify any constraints. Important context like what 'previous captured template' means is missing.
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 coverage is only 33% (only the body parameter has a vague description). The tool description does not explain any parameter meanings or usage. For example, it does not clarify that environmentId is required or what companyId does. The description fails to compensate for the low 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: 'Roll back an environment customImage template to the previous captured template'. It provides the specific verb and resource, and includes the API endpoint and authorization class. However, it does not explicitly differentiate from sibling tools like pc_delete_environments_by_environment_id_custom_image_template, which might cause 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 on when to use this tool versus alternatives (e.g., when to roll back vs. deleting or updating a template). The description does not state prerequisites, conditions, or exclusions. The authorization class is noted but does not help with usage decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it's a write operation, not idempotent, and not destructive. The description adds the HTTP method (POST) and authorization class (board_or_agent), but does not explain side effects like preventing edits.
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 concise but has redundant first sentence. It lacks structure but includes essential HTTP path and auth info.
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 simplicity and presence of output schema, the description still misses important context about what locking entails and when to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50% and the description adds no parameter information. The path parameters 'id' and 'key' lack descriptions, and the optional body parameter is not explained.
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 'Lock' and the resource 'issue document', which is specific and distinguishes it from sibling tools like unlock.
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 the unlock tool. No prerequisites or context for usage 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?
The description adds the authorization class ('board_or_agent') and the exact endpoint, which are not in annotations. However, it does not explain behavioral traits such as what gets destroyed or the irreversible nature of the operation. Annotations already mark destructiveHint true, so the bar is lower; the added auth context provides some value.
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 concise, with three short lines. It is front-loaded with the action and then provides the operation path and authorization. Every sentence adds value, though the structural formatting could be tighter.
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 (restoring a document revision with an output schema and nested objects), the description is incomplete. It lacks details on the outcome of restoration, prerequisites, or consequences beyond the destructive hint. The existence of an output schema is not mentioned or leveraged.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should compensate but does not. It only shows the parameter placeholders in the endpoint path (id, key, revisionId) without explaining their semantics or formats. The agent must infer the meaning from the path structure.
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 'Restore a document revision', which is a specific verb and resource. It distinguishes itself from sibling tools like listing revisions or getting documents, as restoring is a distinct action. However, it does not elaborate on what 'restore' entails beyond the title.
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 only mentions the HTTP operation and authorization class, but no conditions or contexts for using restore over other document revision operations.
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 mentions authorization class and HTTP method. Annotations indicate mutation (readOnlyHint=false) but non-destructive, yet the effect of unlocking is not described. No additional behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences deliver the core purpose and technical reference without any fluff. Front-loaded and 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?
While output schema exists, the description omits important context like side effects, preconditions, or return value meaning. Adequate but leaves gaps for an unfamiliar agent.
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 description does not explain the meaning of 'id' or 'key' parameters. Schema coverage is 50%, but the description provides no parameter details, leaving the agent to infer their roles.
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 unlocks an issue document, but does not differentiate from sibling tools like the lock counterpart, missing an opportunity to clarify its complementary role.
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., lock, update, delete). Prerequisites or context (e.g., document must be locked) are absent.
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 set destructiveHint=true and readOnlyHint=false. The description adds the HTTP operation and authorization class, but does not disclose further behavioral details like what happens to the issue after archiving or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences), but the first sentence repeats the title. It lacks structure such as parameter details or usage context, making it concise but not effective.
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 presence of two required parameters and an output schema, the description is incomplete. It fails to explain the parameters, the effect of archiving, or when this operation is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of the parameters (path.id, body.userId). This leaves the agent without any understanding of what inputs are required or their purpose.
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 'Archive' and resource 'issue from inbox', providing the HTTP method and path, which distinguishes it from siblings like the delete version for unarchiving.
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 on when to use or not use this tool. It does not mention alternatives, prerequisites, or the state of the issue before archiving. Usage is only implied by the name and title.
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 readOnlyHint=false and destructiveHint=false. Description adds the authorization class requirement ('board'). However, it does not disclose other behavioral aspects like side effects or rate limits.
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?
Description is very short and front-loaded with the core purpose. The operation detail is secondary. Could be slightly improved with more context, but overall 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 existence of an output schema and annotations, the description covers the basic purpose. However, for a tool with nested required parameters, more context about the expected structure or behavior would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description provides no explanation of the parameters. The properties 'answers', 'optionIds', 'questionId', etc. are not described. Agent must infer meaning from names alone, which is insufficient for correct invocation.
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?
Description clearly states the tool answers questions on an issue thread interaction. It distinguishes from sibling tools like accept/reject/verdicts by focusing on responding to question interactions. The addition of the API path is extra but not harmful.
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 on when to use this tool versus alternatives. No prerequisites or context provided. The description only states what it does without decision-support.
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 it is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds the authorization class ('board_or_agent') and the API path, which provides some context. However, it does not disclose what marking as read actually does (e.g., affects notifications, is reversible), so the added value is modest.
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 very concise (two sentences) with no superfluous text. It front-loads the purpose. However, its brevity comes at the cost of missing critical details, which prevents a perfect score.
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?
This is a simple state-changing tool. An output schema exists, so return values need not be described. However, the description lacks context on what 'read' means, how it affects the issue lifecycle, and how it relates to sibling tools like deletion. It is minimally adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%, but the description does not explain the parameters at all. It does not mention the required 'id' or the optional 'body' payload, leaving the agent without guidance on how to properly invoke the tool.
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 title and description clearly state the action: 'Mark an issue as read'. The verb+resource pattern is specific and unambiguous. However, it does not differentiate from the sibling tool 'pc_delete_issues_by_id_read' which undoes this action, missing an opportunity to clarify the 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?
No guidance is provided on when to use this tool versus alternatives like 'pc_delete_issues_by_id_read' or other issue manipulation tools. There is no mention of prerequisites, side effects, or typical scenarios.
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 no behavioral context beyond the annotations; it does not explain what 'release' does to the issue (e.g., lifecycle changes, side effects). Annotations already indicate destructiveHint=true.
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 short but includes internal implementation details like endpoint and authorization class that are not helpful for an AI agent; these could be omitted for clarity.
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 importance of a destructive action, the description lacks context about when release is applicable, consequences, or prerequisites; output schema exists but is not leveraged.
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 description provides no explanation of parameters; the required 'path.id' is not clarified, and the optional 'body' is left vague despite 50% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Release' and the resource 'issue', distinguishing it from siblings like 'checkout', 'read', 'archive', etc.
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 on when to use this tool (e.g., prerequisites, typical scenarios) or when not to use it; no alternatives 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 already indicate this is not readOnly or idempotent, implying a standard write operation. The description adds the authorization class ('board_or_agent'), which is helpful but does not disclose additional behavioral traits like side effects or post-condition state.
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 this brevity comes at the cost of missing essential information. It is not verbose but lacks substance for a tool with a complex 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?
Given the complex input schema with nested objects and no descriptions, and the presence of an output schema (unexplained), the description is inadequate. It does not define what a work product is, required field rationale, or expected response format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain parameters, but it provides none. The body parameter is complex with many nested fields (e.g., url, type, title, provider) and no explanation of their meaning or 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 'Create an issue work product' clearly states the verb (create) and resource (issue work product). It distinguishes from sibling tools like GET (pc_get_issues_by_id_work_products) and PATCH (pc_patch_work_products_by_id), as it is the only POST operation for work products.
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 patching or deleting work products. The description lacks context about prerequisites, conditions, or scenarios where creation is appropriate.
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 tool is not read-only, not idempotent, not destructive, and accepts unknown parameters. The description adds the authorization class 'board' and confirms it delivers a payload, but provides no further behavioral detail about side effects, rate limits, or required permissions.
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 concise, consisting of two sentences that front-load the purpose. The second sentence provides additional context (HTTP method and auth class) that, while technical, is arguably relevant for precise usage.
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 a nested parameter and no explanation of the webhook endpoint context, the description is incomplete. It lacks details on return values (though output schema exists), usage scenarios, and prerequisites, making it insufficient for an AI agent to use confidently.
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 50%: only the 'body' parameter has a description, which is minimal. The description does not add any parameter-specific semantics beyond the schema, leaving the 'path' object undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'deliver' and the resource 'external webhook payload to a plugin', making the purpose clear. It does not explicitly differentiate from sibling tools, but no sibling appears to perform the same action.
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 only states the operation and authorization class, but offers no context about prerequisites, use cases, 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?
Annotations already indicate it's a write operation (readOnlyHint=false). The description adds the authorization class 'board_or_agent', which is useful beyond annotations. However, it does not disclose side effects, rate limits, or other behavioral details.
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 short (two sentences) and avoids unnecessary verbosity. However, it lacks structure such as separate sections for parameters or usage notes.
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 complexity (2 required parameters, nested objects, output schema), the description is insufficient. It does not explain what an 'annotation thread' is, when to use it, or what the output contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description offers no explanation of the two required parameters (path and body) or their complex nested structure. This severely impairs correct invocation.
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 'Create a routine description annotation thread', specifying the verb (create) and resource (routine description annotation thread). It distinguishes from sibling tools that handle the same resource with different operations (e.g., get, patch).
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 get or patch. It does not mention prerequisites, conditions, or exclude cases.
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, destructiveHint=false, idempotentHint=false, openWorldHint=true. Description adds that it's a POST operation with authorization class 'board_or_agent'. This context is useful but does not explain side effects like creating a new comment or potential notifications. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with two sentences. It front-loads the purpose and provides technical context. However, it sacrifices explanatory 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?
Given the tool has an output schema, return values need not be explained. However, the description fails to clarify input requirements: what the 'body' field should contain, the fact that 'body' is required, and the relationship between annotation and comment. This makes it incomplete for an agent to use correctly without additional schema inspection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameters. The schema defines path (id, threadId) and body (body, issueCommentId) but their purpose is left entirely to the schema. The description should clarify what each parameter means, especially 'body' content.
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 comment to a routine description annotation. The HTTP path indicates it posts to comments endpoint, distinguishing it from sibling tools that post annotations or patch annotations. However, the description could explicitly say it's for adding a comment to an existing annotation thread.
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 on when to use this tool vs alternatives. Does not mention prerequisites (e.g., annotation thread must exist), or that this tool adds a comment while other tools manage annotations themselves. Sibling tools are listed but not compared.
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 provide readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds the authorization class ('board_or_agent') and the HTTP method, but does not disclose other behaviors like whether triggers can overlap or what happens on duplicate creation.
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 short sentences with no redundant words. However, the first sentence essentially repeats the title, which is slightly wasteful. Still, it's efficiently structured.
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 complexity (nested objects, oneOf, 2 required params, output schema exists but not described), the description is too minimal. It doesn't mention prerequisites (e.g., routine must exist), return value, or error scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% from the description. The description does not explain the oneOf variants (schedule, webhook, api) or any parameter details. The complex input schema requires clarification that the description fails to provide.
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 title and first sentence both state 'Create a routine trigger', clearly indicating the verb and resource. However, it does not differentiate from siblings like pc_patch_routine_triggers_by_id (update) and pc_delete_routine_triggers_by_id (delete).
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 on when to use this tool vs alternatives. For example, it doesn't mention that a routine must exist first or compare with patch/delete operations.
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 readOnlyHint=false and destructiveHint=false, so the tool is a mutation. The description adds authorization class info, but does not disclose side effects, error conditions, or idempotency, which are not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) with no fluff. It front-loads the purpose and adds a technical detail, but the structure is acceptable for a concise definition.
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 complexity of sibling tools and the presence of an output schema, the description is too minimal. It does not explain 'installation grant', relationship to other grant/install tools, or what the optional body does. Lacks completeness for agent decision-making.
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 description does not explain the parameters. Schema coverage is 50% (body has a description, but connectionId lacks one). The description could clarify connectionId's role and the optional body's purpose, but it does not.
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 'Add an installation grant to a tool connection', which clearly identifies the verb and resource. It distinguishes from sibling tools like delete or get grants, though it does not explicitly differentiate from other grant-related operations.
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 mentions 'Authorization class: board', which hints at permissions, but there is no context for choosing this tool over similar grant or installation operations.
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 minimal (readOnlyHint and idempotentHint false), and the description adds no behavioral details beyond the raw endpoint. It doesn't clarify side effects, expected outcomes of the health check, or what happens on success/failure.
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 concise with two lines, but the second line contains raw API details that are not essential for an agent's selection or invocation. It could be streamlined to focus on purpose.
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 nested parameters and an output schema, the description lacks completeness. It does not explain what a health check performs, what response to expect, or error handling, leaving significant gaps for an agent.
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 50% (body described, path not), but the description does not explain any parameters. It adds no meaning beyond the schema, failing to clarify the connectionId or body 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 'Run a tool connection health check' with a specific verb and resource. Among the many sibling tools, this uniquely identifies the purpose of performing a health check on a tool connection.
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. There is no mention of prerequisites, context, or which situations warrant a health check, 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?
Annotations indicate readOnlyHint=false (mutating) and destructiveHint=false (non-destructive), but the description adds no additional behavioral context (e.g., whether the connection is tested, what happens to existing state, or side effects). It only restates the technical endpoint and auth class, which are not behavioral.
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 (two sentences) and front-loads the purpose. The second sentence adds technical reference (endpoint and auth class) which is useful but not verbose. No unnecessary information.
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 two required nested objects in the input schema and no schema descriptions, the description should explain the structure. It fails to do so. With many sibling tools for tool connections, more context about when to reconnect vs patch would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description is the sole source of parameter meaning. However, it only mentions 'replacement credentials' without explaining that 'credentialValues' is a map of key-value pairs or that 'connectionId' is the path parameter. This leaves the agent to infer structure from parameter names alone.
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 'reconnect' and the resource 'tool app', specifying 'with replacement credentials'. This distinguishes it from sibling tools like pc_patch_tool_connections_by_connection_id (which updates other settings) and pc_delete_tool_connections_by_connection_id (deletion).
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 on when to use this tool versus alternatives like patching or deleting. It does not describe prerequisites or typical scenarios for reconnection, making it hard for an agent to decide when to invoke this over similar operations.
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 (destructiveHint false). The description adds the authorization class ('board') and the underlying API endpoint, providing some extra behavioral context but no details on side effects or required permissions.
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 concise with two sentences. It is front-loaded with the core purpose, and the second sentence adds useful technical detail. However, it could be more structured (e.g., bullet points for parameters).
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 3 parameters and no parameter descriptions, the description lacks necessary detail. Even with an output schema present, the description does not cover what the tool returns or its behavioral implications.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameters (e.g., id, companyId). The description adds no semantic 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 ('Approve') and the resource ('deferred tool gateway action request'). It is specific and distinct from sibling tools like decline, though it does not elaborate on what 'deferred' means.
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 on when to use this tool versus alternatives (e.g., other approval-related tools), no prerequisites, and no context for 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and destructiveHint=false, so the description is not required to repeat those. It adds the HTTP method and authorization class, but does not disclose behavioral details such as whether setting company access overwrites existing access or simply adds to it. The output schema exists but is not described, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two short sentences. The first sentence states the core purpose, and the second adds the HTTP endpoint and authorization class. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a write operation with two required parameters and an output schema, the description is incomplete. It does not explain how the body parameter works (overwrite vs. add), error scenarios, or the return value. The annotation provides some context, but the description should fill more gaps for a comprehensive understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about the parameters. It does not explain that 'companyIds' is an array of UUIDs specifying which companies to grant access, nor does it describe the 'userId' parameter or any constraints. The description fails to add meaning beyond the raw 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 'Set company access for a user (admin)', which specifies the verb and resource. It also includes the HTTP method and endpoint, distinguishing it from the GET version (pc_get_admin_users_by_user_id_company_access). However, it does not explicitly differentiate from other admin tools like promote/demote, though the purpose 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks guidance on when to use this tool versus alternatives. It only mentions the authorization class ('instance_admin') as a prerequisite but does not provide context for when to choose this over other admin user operations such as promoting or demoting administrative roles.
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 idempotent, non-read-only, non-destructive. The description adds the HTTP method (PUT) and authorization class ('board_or_agent'), which provides slightly more depth but does not disclose full side effects or preconditions.
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 very concise with two sentences. However, conciseness sacrifices necessary details like parameter semantics and usage context. It could include more information without being verbose.
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 PUT operation that likely replaces an entire list, the description lacks information about whether the update is additive or replaces, what the output contains, and any important constraints (e.g., maximum array size). The output schema exists but is not referenced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain what 'orderedIds' represents or how it affects sidebar preferences. The agent must infer meaning from parameter names alone, which is insufficient for a PUT operation.
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 sidebar preferences for company'), specifying verb and resource. However, it does not differentiate from the sibling tool 'pc_put_sidebar_preferences_me', which may have a different scope, missing an opportunity to distinguish.
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 on when to use this tool versus alternatives (e.g., GET to read preferences, or other PUT endpoints). No prerequisites or contextual cues for 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 indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds the authorization class 'board_or_agent', which is useful. However, it does not disclose behavioral details like atomicity, whether the old policy is overwritten, or error scenarios. The annotations carry most of the burden, and the description adds marginal value.
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, but it lacks substance. It front-loads the purpose but fails to include essential parameter or usage information. Conciseness is valued, but here it sacrifices completeness.
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 (nested objects, required fields, expectedRevision for concurrency), the description is incomplete. It does not explain the full replacement behavior, the need to include all rules each call, or what the response looks like (output schema exists but is not mentioned). The annotations and schema alone are insufficient for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning the description must compensate. The description provides no information about the input parameters (path, body). The complex nested schema with fields like rules, schemaVersion, defaultEffect, expectedRevision is completely undocumented in the description. This is a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Replace the company skill policy' clearly states the action (replace) and the resource (company skill policy). It distinguishes from sibling tools like get and delete by using 'Replace' and specifying the HTTP PUT method in the second sentence.
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 (e.g., patch, delete). It does not explain prerequisites, such as needing to first retrieve the current policy for expectedRevision, or that this is a full replacement. No explicit usage context is 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 idempotentHint=true and destructiveHint=false, so the tool is safe to retry and non-destructive. The description adds the HTTP method (PUT) and authorization class but does not elaborate on further behavioral traits like side effects or response details. Overall, it meets baseline transparency with annotations doing the heavy lifting.
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 purpose, followed by operation details. The first sentence repeats the title unnecessarily, but overall it is efficient with two sentences and minimal wordiness.
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, the description misses contextual completeness: it lacks usage scenarios, parameter explanations, and return value hints. The agent must rely solely on structured fields, which may be insufficient for correct invocation in complex workflows.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should compensate by explaining parameter purpose, but it does not. The input schema itself is self-documenting (e.g., mode enum), but the description adds no additional meaning or context for 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 states 'Update a company user's inbox agent policy', matching the title and specifying the HTTP PUT operation and authorization class. However, it does not explicitly differentiate from the sibling GET tool for the same endpoint, relying on the verb 'Update' to imply 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?
No guidance is provided on when to use this tool versus alternatives, such as the GET counterpart. The description only mentions the authorization class, which is a prerequisite but not contextual usage advice.
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-destructive, idempotent write. The description adds the HTTP method (PUT) and endpoint path, plus authorization class. But it lacks details on failure modes or side effects beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the core purpose, followed by technical context. No filler words.
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 simplicity (one parameter), the description should fully explain parameter semantics. It fails to do so, leaving a critical gap. The output schema exists but is not utilized.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description offers no explanation of the 'body' parameter or its 'orderedIds' field. The agent is left to infer meaning from the schema alone, which is insufficient for correct use.
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 'Update current user sidebar preferences' with a clear verb and resource. It distinguishes from the sibling get tool by its action. However, it does not explicitly contrast with the get tool, leaving some 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 guidance on when to use this tool versus alternatives (e.g., the get tool). It only mentions authorization class but no when-to-use or when-not-to-use advice.
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 destructiveHint=true and idempotentHint=true. The description adds the authorization class 'board_or_agent', which is useful beyond annotations. However, it does not disclose side effects like irreversibility or impact on associated data, which would be valuable for a destructive operation.
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 short (two sentences), but the first sentence repeats the title verbatim without adding value. The second sentence provides useful specifics (URL, auth class). It could be more efficient by starting with the operation details.
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 2 parameters, an output schema, and nested objects, the description is minimal. It does not explain what happens upon deletion (e.g., soft vs hard delete), what the output represents, or any prerequisites. The output schema exists but is not referenced, leaving the agent underinformed.
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 50%, and the description adds no information about parameters. The body field has a generic description, and path.id has none. The description fails to compensate for the gap, leaving the agent without guidance on required inputs.
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 verb 'Delete' and the resource 'agent', and provides the HTTP method and URL. However, it does not differentiate from sibling tools like pc_delete_agents_by_id_instructions_bundle_file, missing an opportunity to clarify scope.
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 mentions the authorization class, giving context on who can use it, but does not specify when to use this tool versus alternatives (e.g., patch vs delete). Usage guidance is implied but not 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 destructiveHint=true. The description adds context by specifying the HTTP method (DELETE) and authorization class ('board'), but does not disclose additional behavioral traits such as scope (current user only) or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, with two short sentences. The purpose is front-loaded, but the second sentence, while informative, could be integrated better. It earns its place without unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation, the description is mostly adequate but omits important context: it does not confirm that deletion is scoped to the authenticated user, nor does it describe the return value or potential errors. Given the output schema exists, the return value gap is mitigated, but usage context is still thin.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 50% schema description coverage, the description adds no extra meaning beyond the schema. It does not explain the purpose or format of `companyId` or `secretId`, nor clarify the optional body parameter.
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 ('Delete') and the resource ('my user secret value'). It distinguishes the tool from siblings that create or update user secrets, 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 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 there any preconditions or context for its use. The description simply states the operation without 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 indicate destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds the authorization class 'board_or_agent' and the HTTP method, which provides additional behavioral context beyond the annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two short sentences that directly convey the purpose and the HTTP method/auth class. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 required parameters with zero schema descriptions and an output schema exists, the description is incomplete as it does not explain parameters or return value. The tool is not self-contained for an agent to invoke correctly without guessing parameter meanings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention any parameters. The input schema has two required parameters (path.id and body.userId) with no descriptions, and the description fails to explain their meanings or usage. Schema coverage is 0%, so the description should compensate but does not.
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 'Un-archive issue from inbox', which is a specific verb and resource. The title and HTTP DELETE method distinguish it from the archive counterpart (pc_post_issues_by_id_inbox_archive). However, the description does not explicitly differentiate from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 lacks any mention of conditions, prerequisites, or scenarios where this tool is appropriate. The sibling list is extensive but no direction 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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds the HTTP method (GET) and authorization class, offering mild behavioral context. However, it does not disclose potential implications like whether the bundle includes resolved templates or raw content.
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) and front-loaded with the main purpose. However, the first sentence repeats the title, and the second provides operation details. It is efficient but misses an opportunity to include parameter context 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?
For a simple read-only tool with one parameter and strong annotations, the description is mostly adequate. However, the lack of parameter explanation and any description of the output (despite an output schema existing) reduces completeness. The tool is easy to use if the agent understands 'id'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one required parameter (path.id) with 0% description coverage in the schema. The description does not mention or explain this parameter, leaving the agent to infer that 'id' likely refers to the agent ID. This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get agent instructions bundle', specifying the verb 'Get' and the resource 'agent instructions bundle'. This distinguishes it from sibling tools like 'pc_patch_agents_by_id_instructions_bundle' (patch) and 'pc_get_agents_by_id_instructions_bundle_file' (file-specific retrieval).
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 on when to use this tool versus alternatives. The description mentions authorization class ('board_or_agent') but does not explain contexts where this retrieval is appropriate or when to use related tools like the file- or patch-based endpoints.
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, clearly indicating a safe read operation. The description adds the HTTP method and authorization class, providing minor additional context 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 description is very concise, consisting of two sentences. However, it lacks structure (e.g., bullet points or sections) and could be more informative without significantly increasing 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?
Given the presence of an output schema, the description does not need to explain return values, but it omits context such as what a 'task session' represents or any filtering capabilities. For a simple tool, this is adequate yet minimally informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate but only restates the parameter structure without explaining the semantics of the 'id' field (e.g., it is the agent ID). This fails to add meaning beyond the input 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 title and description clearly state the tool lists agent task sessions, providing a specific verb and resource. However, it does not explicitly differentiate from sibling tools like pc_get_agents_by_id, which retrieves agent details, but the name and context make the purpose distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks guidance on when to use this tool versus alternatives. It does not specify prerequisites, scenarios, or exclusions, leaving the agent without context to choose optimally among sibling 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?
The description adds that it's a GET operation (safe) and 'Authorization class: public' (no auth needed), which supplements the annotations. No contradictions, but does not describe other behavioral aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: two sentences with no wasted words. The first sentence is redundant with the title, but the structure is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with annotations, the description provides the endpoint and auth class. However, it lacks parameter explanation and usage context, leaving gaps for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no parameter descriptions). The description mentions the endpoint path with {id} but does not explain what the 'id' parameter represents, leaving the agent to infer its meaning.
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 'Get a CLI auth challenge' with the HTTP method and endpoint, distinguishing it from sibling tools that create, approve, or cancel challenges. However, it adds little beyond the title and endpoint.
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 on when to use this tool versus alternatives like pc_post_cli_auth_challenges, pc_post_cli_auth_challenges_by_id_approve, etc. The description lacks explicit usage 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 indicate read-only, idempotent, non-destructive behavior. The description adds the HTTP method and authorization class, which provides some additional transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first restates title, second adds technical detail. Front-loaded with purpose, but the repetition is slightly wasteful. Generally efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema exists, so return format is covered. However, the description is minimal and does not help distinguish from similar tools like model_profiles. Adequate but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate. It only implies parameters (companyId, type) without explaining their meaning or valid values. Minimal 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 'List models for an adapter type' with a specific verb and resource. However, it does not differentiate from sibling tools like 'pc_get_companies_by_company_id_adapters_by_type_model_profiles', which could be confused.
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 on when to use this tool versus alternatives. The description only provides the API path and authorization class, but no context on prerequisites or scenarios.
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 (readOnlyHint, etc.) already indicate a safe read. Description adds the exact HTTP GET method and authorization class ('board_or_agent'), providing useful context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. The most critical information is front-loaded: verb, resource, and operation details.
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 an output schema existing, the description omits what 'agent configurations' are, how the list is structured, or any filtering options. With many sibling tools, the agent lacks context to choose correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain the sole parameter 'companyId'. While it is inferable from context, the lack of explicit description leaves ambiguity about format or constraints.
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 title and description clearly state 'List agent configurations for a company', providing a specific verb and resource. It distinguishes from sibling 'pc_get_companies_by_company_id_agents' which lists agents, not configurations, but does not explicitly differentiate.
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 on when to use this tool versus alternatives like pc_get_companies_by_company_id_agents. No context about prerequisites or scenarios provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds the HTTP method and authorization class, which provide extra behavioral context. Given annotations cover safety, the description adds modest value.
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 purpose. However, it is overly terse and omits useful details. Conciseness is valued, but not at the expense of completeness.
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 a single parameter and an output schema, the description does not explain key aspects like what 'decision-only' means or any filters. For a simple listing endpoint, it partially covers, but significant context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. Although there is only one parameter (companyId), the description does not mention it or explain its meaning. The agent must infer from the URL, which is suboptimal.
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 'List decision-only attention feed items' clearly states the action and resource. However, it does not distinguish this tool from siblings like pc_get_companies_by_company_id_timeline. The purpose is clear but lacks 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?
No guidance on when to use this tool versus alternatives. There is no mention of conditions, prerequisites, or exclusions. The agent is left uninformed about appropriate usage 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 indicate readOnlyHint=true, destructiveHint=false, so the agent knows it's safe. The description adds the authorization class 'board_or_agent' and confirms it's a GET operation, providing some extra behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded with the title and endpoint. Every sentence serves a purpose, though it could be expanded slightly to include parameter info without losing 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?
For a simple read-only tool with one parameter and an output schema (not shown), the description provides basic context: title, endpoint, auth class. It does not describe the output structure or behavior like pagination, but given the output schema exists, this is acceptable.
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 one required parameter (path.companyId) with no description. The tool description does not mention this parameter or its purpose, leaving the agent to infer from the endpoint. Given 0% schema coverage, the description should compensate.
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 it's a 'Cost report: by-project' and provides the REST endpoint GET /api/companies/{companyId}/costs/by-project, indicating it retrieves cost data grouped by project. The title reinforces this, helping differentiate it from sibling cost tools like by-agent or summary.
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 pc_get_companies_by_company_id_costs_by_agent or pc_get_companies_by_company_id_costs_summary. There is no mention of prerequisites, limitations, or typical use cases.
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. The description adds the HTTP method (GET) and the authorization class ('board_or_agent'), which go beyond annotations. However, it does not disclose pagination behavior, result limits, or any side effects (though none are expected). The added context is useful but not extensive.
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 very concise, consisting of two sentences that front-load the purpose and include the key HTTP operation and auth info. Every sentence adds value without redundancy. It is slightly short but acceptably so for a straightforward list tool.
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 that the tool has only one parameter and an output schema exists, the description is minimally adequate. It explains what the tool does and provides the auth class, but it does not describe the output format or content. It also does not mention that the companyId is required or how to obtain it. For a list tool, more context about result scope or potential emptiness would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter meaning. The only parameter, path.companyId, is not explained in the description. While the name is somewhat self-explanatory, the description does not elaborate on its format, how to obtain it, or its role in identifying the company. This leaves a semantic gap.
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 verb 'List' and the resource 'environments for a company'. It also provides the HTTP method and path, making the purpose unambiguous. However, it does not differentiate among sibling tools that also operate on company environments (e.g., pc_post_companies_by_company_id_environments or pc_get_companies_by_company_id_environments_capabilities), 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?
The description does not provide guidance on when to use this tool versus alternatives. It does not mention that to retrieve a specific environment one should use pc_get_environments_by_id, nor does it offer any exclusions or preferred contexts. The only additional info is the authorization class, which is not decision 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. The description adds the HTTP method (GET) and authorization class, which provide some additional behavioral context. However, it does not disclose any other traits such as whether the output is filtered or paginated, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded, using only two sentences plus endpoint details. It avoids redundancy and is efficient. However, it could incorporate additional useful information without being 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?
With an output schema present, the return value is implicitly documented. However, the description lacks context about what 'sidebar preferences' entail, how 'me' scopes the results, and how this tool differs from the sibling pc_get_sidebar_preferences_me. For a tool with a single parameter and good annotations, this is minimally adequate but not thorough.
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 a single parameter (companyId) with no description (0% coverage). The tool description also fails to describe this parameter, leaving the agent to infer its meaning from the tool name. It does not clarify that the endpoint returns preferences for the current user ('me') within that company.
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 'Get sidebar preferences for company' which clearly identifies the resource and action. The endpoint path provides additional context. However, it does not explicitly differentiate from the sibling tool 'pc_get_sidebar_preferences_me' which might have a similar purpose without a company filter.
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 authorization class 'board_or_agent' is mentioned, but there is no discussion of prerequisites, scenarios, or why one would choose this over pc_get_sidebar_preferences_me or other similar 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?
The description adds the authorization class ('board_or_agent') beyond what annotations declare (readOnlyHint, idempotentHint, destructiveHint). However, it does not disclose what happens if the skill is not found or other behavioral nuances. The annotations already cover safety, so the description's added value is marginal.
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 very concise, with two short sentences that front-load the purpose. It avoids unnecessary detail, though it could be slightly more informative without losing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic purpose and authorization, but lacks usage guidance and parameter explanations. An output schema exists, so return values are covered, but the overall completeness is marginal for a tool with many siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the meaning of companyId or skillId. It relies on the path structure and tool name, which is insufficient for an agent to infer parameter semantics without schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'a company skill', which accurately describes the tool's purpose of retrieving a specific skill for a company. It is sufficiently differentiated from sibling tools that list or manage skills in other ways, though it could be more explicit about returning a single skill.
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 listing all company skills (pc_get_companies_by_company_id_skills) or other skill-related tools. There is no mention of use cases 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?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the tool's safety profile is known. The description adds that it's a 'Paperclip operation' and the authorization class, which provides some behavioral context but does not disclose details like pagination or ordering. With annotations covering key traits, the description adds marginal value.
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 (three sentences) and to the point. However, the first sentence is redundant with the title. It is concise but lacks substance for completeness.
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 there is an output schema, the description lacks parameter guidance (no descriptions for companyId or skillId) and does not mention pagination, filtering, or the scope of comments returned. It is insufficient for an agent to reliably use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not describe any parameters. The URL pattern implies companyId and skillId, but no explanation of what they represent or how to obtain them is given. This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List skill comments' clearly states the action (list) and resource (skill comments). The tool name includes the full path, and it is distinct from sibling tools like pc_get_companies_by_company_id_skills_by_skill_id (get skill) and pc_post_companies_by_company_id_skills_by_skill_id_comments (create comment).
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 on when to use this tool vs alternatives. It does not mention that this lists all comments for a skill, while other tools exist for single comment retrieval, creation, or deletion. The authorization class is mentioned but does not inform usage 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 readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds the HTTP method (GET) and authorization class, which are consistent. However, it does not disclose additional behavioral details such as pagination, response format, or side effects beyond what annotations imply.
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 brief and front-loaded, containing only three short lines. It repeats the title 'List skill files' but avoids unnecessary verbiage. The structure is clear, though the title repetition could be removed without loss.
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 that an output schema exists, return values need not be described. The tool has nested parameters (path object) with two required string fields, but the description does not clarify how to structure the request body. For a simple list operation, the description is mildly adequate but could be more helpful, especially in context of many similar tools.
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 parameter coverage is 0%, meaning no descriptions are provided in the input schema. The description only restates the path pattern but does not explain the meaning or constraints of companyId or skillId. Although the parameter names are self-explanatory, the description adds no value beyond the schema structure.
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 'List skill files' which is a clear verb+resource. The HTTP path further specifies the resource as skill files associated with a company and skill ID. However, it does not explicitly differentiate this from sibling file-listing tools (e.g., for catalog files), though the path and names are distinct.
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. There is no mention of prerequisites, typical use cases, or situations where another tool like pc_get_skills_catalog_by_catalog_id_files 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.
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, covering safety. The description adds Authorization class ('board_or_agent'), which is useful authentication context beyond annotations. However, it doesn't disclose other behaviors like pagination, ordering, or response format.
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 very short—two sentences—with the purpose front-loaded. The second sentence adds operational detail (HTTP method, auth class) that is not strictly necessary but not harmful. It earns its place, though the structure could be tighter.
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 an output schema present, the description need not explain return values. However, it omits details like whether the list is paginated, ordered, or filtered. Given the tool's simplicity and annotation coverage, the description is minimally adequate but leaves gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the two required parameters (companyId, skillId). It fails to provide any meaning or context beyond the names, which are standard but the agent might benefit from clarification (e.g., where to find these IDs).
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 'List skill test inputs', which clearly indicates the verb and resource. The tool name itself is specific, and among siblings like post and delete, the list action is distinguishable. However, it does not elaborate on what 'test inputs' are, so it's not maximally helpful.
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 (e.g., post, delete siblings). It does not specify prerequisites or context for listing. This lack forces the agent to infer usage from the tool name alone.
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 read-only, idempotent, non-destructive. The description adds the HTTP method and authorization requirement (board_or_agent), providing useful context. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, but it sacrifices necessary detail. While concise, it is too sparse to be effective.
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 complexity of the sibling tools and the lack of parameter descriptions, the description is inadequate. It does not explain what a test run is, how the list relates to other test-run tools, or any pagination/return details. An output schema exists but overall context is missing.
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 no parameter descriptions (0% coverage), and the description does not explain the meaning of companyId, skillId, or the optional inputId. The agent must infer from the tool name, which is insufficient.
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 (List) and resource (skill test runs), and the title matches. It distinguishes from sibling tools like the POST create tool by the verb, though it does not explicitly differentiate from other GET test-run tools. The HTTP path provides additional 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 (e.g., creating a test run, getting a specific test run). It only mentions the HTTP method and authorization class, but no use case or scenario.
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, destructiveHint=false. The description adds the authorization class 'board_or_agent' and the HTTP method, which provides minor additional transparency but does not describe error handling or effects beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short with two sentences, front-loading the purpose and key details. The first sentence is redundant with the title, but overall it is concise and structured efficiently.
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 output schema exists (reducing the need to describe return values), the description still lacks guidance on prerequisites, how to obtain parameter values, or typical error scenarios. It is minimally adequate for a simple read operation with safe annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the three required path parameters (companyId, skillId, versionId). The mention of the URL pattern gives minimal context but does not compensate for the missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The title 'Get a skill version' and description including the HTTP path clearly indicate the tool retrieves a specific version of a skill. It distinguishes from sibling tools like pc_get_companies_by_company_id_skills or pc_get_companies_by_company_id_skills_by_skill_id_versions.
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 listing all versions or getting a skill. The description lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds the HTTP method and auth class, which is marginal value but not contradictory. Additional context like pagination or rate limits is missing.
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 lines) but front-loaded with purpose. However, it lacks useful detail that could be included concisely, such as the scope of listing (by company) or response type.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with a single parameter and robust annotations, the description is minimally complete. However, it does not clarify what 'tool applications' are or how the list relates to siblings. The output schema exists but is not referenced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no parameter descriptions). The description does not explain the required companyId parameter or its usage. It adds no value beyond the schema structure.
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 title 'List tool applications' and description 'List tool applications' clearly state the verb and resource. The tool name and sibling tools (e.g., pc_post_companies_by_company_id_tools_applications, pc_delete_tool_applications_by_application_id) distinguish this as a read-only list 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 on when to use this tool vs alternatives. Siblings exist for create, update, delete but the description provides no context like 'use this to view all installed applications' 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.
Behavior3/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. The description adds the HTTP GET method and authorization class 'board', which provides minor additional context. It does not explain what a 'named MCP gateway' is or what the response contains (though an output schema exists). The description adds some value beyond annotations but is still limited.
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 very short (two sentences) and front-loaded, with no fluff. It repeats the title but adds the HTTP method and auth class. It could be slightly more structured but is efficient for the information provided.
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 presence of an output schema, the description does not need to detail return values. However, it fails to state that the tool lists all gateways for a company, or mention any filtering or pagination. For a simple single-parameter tool, it is moderately complete but could be improved by clarifying the scope (all gateways for a company).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the required 'companyId' parameter. The implicit mention in the URL path is insufficient. The agent must infer that companyId is the company identifier, but no format or usage details are given.
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 it lists named MCP gateways, repeating the title. The HTTP method and auth class are added. However, it does not differentiate from sibling tools that also list gateways (e.g., pc_get_mcp_gateways_by_gateway_public_id lists a specific gateway). The purpose is clear but lacks explicit 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?
No usage guidelines are provided. The description does not indicate when to use this tool versus alternatives like pc_get_mcp_gateways_by_gateway_public_id or pc_post_companies_by_company_id_tools_gateways. The sibling tool list is extensive but no guidance is 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, destructiveHint=false, so the safety profile is clear. The description adds the authorization class ('board'), which provides useful context beyond annotations. No contradictions are present, but the description does not further disclose behavioral traits like rate limits or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded: two sentences effectively convey the core purpose and operation details. Every sentence adds value (title, HTTP method, auth class) with no redundancy. However, slightly more detail on parameters could be added without harming 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 the tool's complexity and the presence of an output schema, the description is too sparse. It does not explain what 'effective tool access profiles' means, how the agent's identity is resolved, or when this tool is relevant. The annotations cover safety, but the description lacks enough context for an agent to decide whether to use this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description does not explain the purpose of companyId or agentId. It only mentions the path structure without defining the parameters' roles or constraints. This leaves the agent with no semantic guidance for constructing valid inputs.
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 resolves effective tool access profiles for an agent using a specific verb ('Resolve') and resource ('effective tool access profiles for an agent'). The title and first sentence align, and the operation info adds the HTTP method, making the purpose unambiguous. It distinguishes itself from sibling tools by its unique resource path.
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 other profile-related tools (e.g., pc_get_companies_by_company_id_tools_profiles, pc_patch_tool_profiles_by_profile_id). The description lacks exclusions, prerequisites, or contextual hints, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that it's a GET operation and auth class, but does not disclose any behavioral traits beyond what annotations imply. 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 short and to the point. It includes a technical note about the HTTP method and auth class, which is informative without being 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?
Given the tool has an output schema, the description could mention what the response contains. The purpose is clear, but the lack of differentiation from many sibling tools and missing parameter explanations reduce completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain the path parameter or companyId. Although the parameter is simple, the description fails to add value beyond the schema for a low-coverage scenario.
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 it lists user secret definitions. The title matches. It is a specific verb+resource, though it does not elaborate on what a user secret definition is compared to other secret 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?
No guidance on when to use this tool versus alternatives like pc_get_companies_by_company_id_secrets or other list operations. The description lacks context for decision-making.
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 description adds modest value by specifying the Paperclip operation and authorization class. No contradictions. However, it does not detail what 'events' entail or any side effects beyond what annotations cover.
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 (two sentences) and front-loaded with the title, but it omits crucial parameter details. It is concise but at the expense of completeness, earning a mid-range score.
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 one parameter with no description coverage, and the description does not clarify the return value or the nature of 'events'. Annotations provide safety context, but the overall description is insufficient for an agent to use correctly without additional knowledge. Output schema exists but is not referenced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description fails to explain the single parameter 'path.runId'. It does not indicate how to obtain the runId or what constitutes a valid runId. The description provides no additional meaning beyond the schema structure.
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 it gets events for a heartbeat run, which is specific and distinguishes it from sibling tools like pc_get_heartbeat_runs_by_run_id (which gets the run itself) and pc_post_heartbeat_runs_by_run_id_cancel (which cancels a run). The verb 'get' and resource 'events' are 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?
No guidance is provided about when to use this tool versus alternatives, such as pc_get_heartbeat_runs_by_run_id_log for logs or pc_get_heartbeat_runs_by_run_id_issues for issues. There is no mention of prerequisites, context, 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?
The description adds the HTTP method (GET) and authorization class ('board_or_agent'), which supplements the annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint). The description is consistent with annotations and provides moderate behavioral context, but it does not disclose additional behavioral traits such as rate limits or data volume.
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 succinct, comprising two sentences with the purpose and HTTP details. It is front-loaded with the action and resource, but the second line could be integrated for better readability. Overall, it is efficient with no superfluous text.
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 complexity of the tool (nested parameter, output schema present), the description is insufficient. It does not explain what 'bounded subtree' means, how diagnostics are structured, or how this tool relates to siblings. The presence of an output schema reduces the need to describe return values, but the usage context and parameter details are lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema includes a required nested 'path' object with an 'id' string property, but the description provides no explanation of the parameter. With 0% schema description coverage, the description fails to add any meaning beyond the schema, leaving the agent without guidance on how to construct the path.
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 retrieves 'bounded subtree wake and blocker diagnostics for an issue.' The verb 'Get' and resource 'diagnostics' are specific, and the combination of 'wake and blocker' with 'subtree' distinguishes it from sibling tools like pc_get_issues_by_id_diagnostics_blockers and pc_get_issues_by_id_diagnostics_wakes, which handle individual diagnostics.
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 does not indicate that this tool returns diagnostics for the entire subtree, while sibling tools might return direct diagnostics, leaving the agent to infer usage context without explicit when-not or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, idempotentHint, and destructiveHint false, which the description echoes. Additionally, the description provides the authorization class ('board_or_agent'), adding context beyond annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two sentences) but includes some redundancy with the title and a technical route string. It is functional but not optimally concise for an AI agent.
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 presence of an output schema and many sibling diagnostics tools, the description lacks sufficient context about the meaning of 'wake diagnostics' and what the response contains. The agent may struggle to decide when to use this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'path.id' parameter (e.g., it is the issue ID). The description fails to compensate for the missing schema descriptions, leaving ambiguity about the required input.
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 retrieves 'wake diagnostics' for an issue, using a specific verb and resource. The name distinguishes it from sibling diagnostics tools like 'blockers' and 'subtree', 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., pc_get_issues_by_id_diagnostics_blockers). No prerequisites or conditions provided. The agent must infer context 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.
Behavior3/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 authorization class and endpoint, but does not disclose additional behavioral traits like error responses or return format. Minimal extra value.
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 very short (3 sentences) and front-loaded with the purpose. However, it is too terse and lacks detail, leaving the agent with minimal information.
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 simplicity of a read-only get operation and the presence of annotations and output schema, the description is minimally adequate. However, it does not differentiate from siblings or describe output, leaving room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the meaning of 'id' or 'key' parameters beyond the endpoint path. The names are somewhat self-explanatory, but the description should compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get an issue document' clearly indicating the tool retrieves a single document for an issue. The endpoint path and authorization class are included, but no explicit differentiation from siblings like pc_get_issues_by_id_documents (list all documents) or pc_put_issues_by_id_documents_by_key (update document).
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 the operation and path, with no mention of prerequisites, use cases, 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?
Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds the endpoint and auth class but no further behavioral traits beyond what is already implied.
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?
Description is concise with two sentences plus a line for operation and auth. It is front-loaded but could be structured slightly better with parameter explanations.
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 simple read tool, it is somewhat complete but lacks parameter documentation and usage context. Output schema exists but description does not leverage it to clarify return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, and the description does not explain any of the parameters (id, key, threadId). The agent lacks semantic understanding of required inputs.
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?
Title 'Get a document annotation thread' and description clearly state the action and resource. It distinguishes from siblings like the list endpoint by specifying a single thread via threadId.
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 on when to use this tool versus alternatives such as listing annotations or other operations. The description only provides the HTTP method and auth class, not usage 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 readOnlyHint: true, idempotentHint: true, destructiveHint: false, indicating safe read operation. The description adds the HTTP method (GET) and authorization class (board_or_agent), which provides additional behavioral context not in annotations. However, it lacks details on pagination, response format, or error handling. With annotations covering safety, the description adds modest value.
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 very concise, with the purpose front-loaded in the first line. The second line adds technical details (HTTP method, authorization class) without unnecessary verbosity. It is efficient but could be slightly more structured; however, it earns a 4 for being lean and relevant.
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 simplicity (1 parameter, read-only, output schema exists), the description is moderately complete. It covers the basic purpose and technical details but omits information about what feedback votes represent, any filtering options, or pagination. An agent might need to infer context from usage. The presence of an output schema reduces the need to describe return values, but the description remains somewhat terse for full contextual completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, path.id, has no description in the schema (0% coverage). The tool description does not explain this parameter, leaving the agent to infer that it is the issue ID. While the parameter name is somewhat self-explanatory, the lack of any parameter description in both schema and description means the agent must rely on heuristics. A higher score would require explicit mention of the parameter's role.
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 'List issue feedback votes' clearly states the action (list) and the resource (feedback votes), which aligns with the title. It distinguishes this tool from sibling tools like pc_get_issues_by_id_comments and pc_get_issues_by_id_approvals by focusing on feedback votes specifically. However, it does not elaborate on what feedback votes entail, so it's clear but not exceptionally detailed.
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 or when to use alternatives. There is no mention of context, prerequisites, or exclusionary criteria. An agent would have to infer from the resource name that it's for listing feedback votes, but no explicit usage advice is 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 the tool as read-only, idempotent, and non-destructive. The description adds the HTTP method (GET) and authorization class (board_or_agent), which are not in annotations but provide minor additional 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 very short and front-loaded with the purpose. It contains no wasted words, but could slightly expand on the parameter without losing 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?
For a simple list operation with one parameter and an output schema, the description is adequate but lacks explanation of the parameter and what recovery actions are. It provides the basic context needed to understand the tool's role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'path.id' parameter. Although the tool name implies 'id' is the issue ID, the description should explicitly state this to guide correct usage.
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 title and first line clearly state the verb 'List' and the resource 'issue recovery actions', providing a specific purpose. However, it does not differentiate from sibling tools like 'pc_get_issues_by_id_approvals' or explain what recovery actions are in this context.
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 vs alternatives. No explicit when/when-not or alternative tools mentioned, leaving the agent to infer usage context from the tool 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?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds the HTTP method (GET), endpoint path, and authorization class ('board_or_agent'). This provides additional context beyond annotations but does not disclose other behavioral traits like pagination or rate limits.
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 very concise with two sentences that are front-loaded and directly relevant. The first sentence states the purpose, and the second adds technical details. No unnecessary information.
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 presence of an output schema, annotations, and only one parameter, the description is adequate. However, it lacks guidance on prerequisites (e.g., whether the issue must exist) and does not mention return format or pagination. The annotations cover safety, so the tool is usable but not fully comprehensive.
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 1 parameter (path.issueId) with 0% schema description coverage. The description does not explain the meaning, format, or constraints of the issueId parameter beyond implying it identifies an issue. The description does not compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists live runs for a specific issue with verb 'list' and resource 'live runs'. The title reinforces this. It is specific enough to distinguish from many siblings, though it does not explicitly differentiate from similar tools like 'pc_get_issues_by_id_runs'.
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. There is no mention of prerequisites, context, or situations where this tool should be avoided. The description only states what the tool does, not when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the HTTP method (GET) and authorization class ('board'), but the key behavioral traits (read-only, idempotent, non-destructive) are already covered by annotations. The description does not elaborate on what the config contains or any potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (three lines) with no extraneous text. However, the second line ('Paperclip operation...') is internal implementation detail that may not be universally helpful. It remains concise and 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?
Despite annotations covering safety, the description lacks parameter explanations, does not describe the output (even though an output schema exists), and offers no context about the config structure or error conditions. This leaves the agent with significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description does not explain the parameters (pluginId, companyId). The agent must infer their meanings from context. The title implies companyId is for company scoping, but no explicit guidance is given.
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 title and first sentence clearly state 'Get company-scoped plugin config', specifying the verb (get), resource (plugin config), and scope (company). This distinguishes it from sibling tools like pc_get_plugins_by_plugin_id (which gets the plugin itself) and pc_post_plugins_by_plugin_id_config (which updates config).
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 guidelines are provided. The description does not explain when to use this tool versus other plugin tools like pc_get_plugins for listing or pc_post_plugins_by_plugin_id_config for updating. There is no mention of 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.
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. Description adds the specific HTTP method (GET) and endpoint, plus authorization class, providing some additional context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is short (two sentences plus title) with no redundant information. However, the title and first sentence repeat the same idea, which is slightly inefficient but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, the description covers purpose, HTTP method, and auth. However, it omits details about the response (e.g., return type, structure) and any filtering or pagination, which would be helpful for an agent. The presence of an output schema partially mitigates this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% with no descriptions for the required 'id' parameter. The description implies 'id' is a project ID but does not explicitly clarify its purpose or format, so it fails to compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'List' and resource 'project workspaces', and provides the exact HTTP endpoint. However, it does not distinguish it from sibling tools like pc_post_projects_by_id_workspaces for creation, leaving the agent to infer uniqueness.
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 on when to use this tool vs alternatives. Mentions authorization class but does not specify when to use or when not to use, or contrast with related tools like pc_get_companies_by_company_id_execution_workspaces.
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, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds the endpoint and auth class, providing extra context about authentication needs. However, it does not disclose behavior on missing IDs or other edge cases. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact at two sentences, but the second sentence contains technical implementation details (HTTP method, auth class) that may be more appropriate in annotations or schema. Still, it is concise and free of fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and an output schema, so the description does not need to explain return values. However, it lacks an explanation of what a secret provider configuration is or when to fetch one, which would help an agent understand its relevance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description does not add any meaning to the single parameter (id). While the parameter is simple, the description should have clarified its purpose (e.g., 'the ID of the secret provider configuration to retrieve').
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 'Get a secret provider configuration', which is a clear verb+resource purpose. However, it does not explicitly distinguish this tool from its sibling 'pc_get_companies_by_company_id_secret_provider_configs' (which lists all configs), missing an opportunity to differentiate by scope.
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 only includes technical details (HTTP method and auth class) rather than contextual usage criteria, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds the endpoint and authorization class, but no additional behavioral context like pagination or response format. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two lines) and front-loaded with the main purpose. However, it omits useful details that could be added without verbosity.
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 parameter and existing annotations, the description is minimally adequate. It lacks parameter documentation and return value info, and does not help differentiate from related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% for parameter descriptions. The only parameter, catalogId, is a string in path, but the description does not explain its format or meaning. Baseline is lowered due to lack of compensation.
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 'List catalog skill files', which is a specific verb and resource. It distinguishes from sibling tools like pc_get_skills_catalog_by_catalog_id (get catalog metadata) and pc_get_teams_catalog_by_catalog_id_files, but does not explicitly differentiate them.
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 on when to use this tool versus alternatives (e.g., pc_get_companies_by_company_id_skills_by_skill_id_files). The HTTP method and auth class are provided but not contextualized.
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, idempotentHint, and destructiveHint false. The description adds that it is a GET operation and the authorization class. With annotations covering the safety profile, the description adds minimal new 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 very concise, with two short sentences. It front-loads the title and includes the HTTP method and path. However, the brevity sacrifices necessary detail, making it efficient but not sufficiently informative.
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 existence of an output schema and the tool being a simple read operation, the description is minimally adequate. However, it lacks context about the relationship to other catalog tools and does not explain what the response contains beyond implication.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'catalogId' parameter. It only mentions the path template. The parameter's purpose, format, or constraints are not clarified, which is a significant gap.
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 'Get catalog team', which is a clear verb+resource. The HTTP method and path are provided. However, it does not differentiate this tool from siblings like pc_get_teams_catalog (list) or pc_get_skills_catalog_by_catalog_id, so the purpose is clear but not distinct.
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. There is no mention of prerequisites, context, or comparison to sibling tools. The auth class is noted but does not help with usage decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds the HTTP method and auth class, which is useful but does not disclose other behaviors like error handling or rate limits.
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?
Extremely concise: two short sentences. No wasted words. The first sentence states the purpose, the second provides endpoint and auth context.
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, the description lacks context about workspace operations, how operationId is obtained, or the structure of the log. Given the tool's specificity and sibling tools, more context is needed for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It does not explain what operationId represents or where to obtain it. The parameter is just mentioned in the endpoint path without elaboration.
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 verb 'Get' and resource 'log for a workspace operation'. It also provides the API endpoint and auth class. However, it does not explicitly differentiate from sibling tools like pc_get_execution_workspaces_by_id_workspace_operations, though the name includes 'log'.
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, what prerequisites are needed, or what kind of operations this applies to. The agent gets no context for appropriate invocation.
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 tool is not read-only and not destructive; the description adds that it is a PATCH operation and requires 'board' authorization. This provides moderate behavioral context, though it does not discuss side effects, reversibility, or the meaning of 'openWorldHint'.
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 very concise (two sentences). However, the technical details (HTTP method, auth class) are appended as a separate sentence, which could be integrated more smoothly. The brevity is generally appropriate, but it sacrifices necessary 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 (nested parameters, enums, output schema, many siblings), the description is incomplete. It does not explain what 'general' settings encompass, how the body fields behave, or how this tool differs from closely related siblings like 'pc_patch_instance_settings'. The output schema is not discussed either.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description does not mention any parameters or their meanings. The 'body' parameter with nested fields (executionMode, backupRetention, etc.) is left completely unexplained. This forces the agent to rely solely on parameter names, which is insufficient for correct 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 clearly states 'Update general instance settings', which is a specific verb+resource combination. It distinguishes from sibling tools like 'pc_get_instance_settings_general' (read vs write) and 'pc_patch_instance_settings' (targets different settings). The addition of the HTTP method and endpoint further clarifies the purpose.
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 'pc_patch_instance_settings' or other update tools. It does not mention prerequisites, exclusions, or use cases. The agent is left to infer context from the tool 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 indicate readOnlyHint=false (write operation) and destructiveHint=false. The description adds 'Update' and the HTTP method (PATCH), but does not explain behavioral traits like partial updates, immediate effects, or potential side effects. With openWorldHint=true, more transparency would be beneficial.
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 to the point, consisting of two sentences. It is efficient but could be improved by adding parameter context without sacrificing 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 the tool's complexity (nested objects, many parameters, output schema exists), the description is too minimal. It does not explain what a tool access profile entry is, how updates work, or any nuances. The absence of parameter descriptions makes the tool difficult to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning no parameter descriptions in the schema. The description itself does not describe any parameters, leaving the agent to infer meaning from names alone. This is insufficient for correct 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 clearly states 'Update a tool access profile entry', with a specific verb and resource. The HTTP method and path provide further precision. The tool name distinguishes it from sibling tools like 'pc_post_tool_profiles_by_profile_id_entries' (create) and 'pc_delete_tool_profile_entries_by_entry_id' (delete).
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 the HTTP method and authorization class, offering some guidance. However, it lacks explicit 'when to use' or 'when not to use' instructions relative to siblings. The naming convention implies this is for updating existing entries, but this is not directly 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 readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds the authorization class ('board_or_agent') and HTTP method (POST), suggesting a non-idempotent mutation. However, it does not disclose side effects, rate limits, or other behavioral traits beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single sentence stating the purpose, followed by operational details. It is front-loaded and contains no unnecessary words.
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 two parameters and existing output schema, the description lacks explanation of when clearing an error is appropriate, preconditions, or the meaning of the response. The auth class adds some context, but overall completeness is low.
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 50%—only the 'body' parameter has a description, and it is vague. The description does not mention or clarify any parameters, leaving the 'path.id' parameter undocumented. It fails to add 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 'Clear an agent error' and provides the HTTP operation and authorization class. It is specific to this tool and distinguishes it from siblings like pc_post_agents_by_id_pause or pc_post_agents_by_id_approve. However, it does not elaborate on what constitutes an agent error.
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, prerequisites, or context such as when an agent error occurs. The description lacks any 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?
Annotations indicate it's a write operation (readOnlyHint=false). The description adds authorization class (board_or_agent), but no details on side effects, reversibility, or rate limits. Minimal extra value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no waste. However, the technical details (Paperclip operation, authorization class) could be integrated more clearly. Still concise and 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?
A mutation tool with 2 required parameters and no parameter descriptions. Output schema exists but is not referenced. Lacks explanation of prerequisites, success/failure outcomes, or typical use case. Inadequate for full context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not mention parameters (path id and body token) at all, leaving the agent to infer their purpose from names alone.
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 (approve) and resource (CLI auth challenge), along with the HTTP method and path. It is specific and distinct from sibling tools like cancel and revoke.
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 on when to use this tool vs. alternatives (e.g., cancel or revoke). No prerequisites or context for invocation.
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 mutation (readOnlyHint=false) but non-destructive (destructiveHint=false). The description adds authorization class and HTTP method, but does not discuss idempotency, side effects, or error conditions. With annotations covering some traits, the description provides modest added 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 very short (two sentences) and front-loaded with the core action. However, the second sentence includes technical details (Paperclip operation, authorization class) that may not be essential for an AI agent. Still, it is efficient.
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 covers the basic purpose and auth requirement, but lacks information on prerequisites, what happens on success/failure, and how to disable. The presence of an output schema partially mitigates the need to describe return values, but overall completeness is low for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description provides no explanation of the parameters (companyId, key, routineKey, body). Although some names are suggestive, the agent must infer meaning from context alone. This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The title and description clearly state the action: 'Enable a built-in routine schedule.' This distinguishes it from sibling tools like provision, reset, or reconcile, which have different purposes. The HTTP path further clarifies the resource being acted upon.
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 on when to use this tool versus alternatives. It does not mention prerequisites (e.g., the built-in agent must exist, the routine must be disabled first) or when not to use it. The description is purely declarative.
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 readOnlyHint=false and destructiveHint=false, so the description adds only the authorization class. This is useful but minimal. No details on potential side effects or behavior beyond creation.
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 sentences, no fluff. It front-loads the purpose and includes relevant endpoint and auth info. 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.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even with an output schema, the description lacks completeness: no input parameter explanations, no info about label uniqueness, color validation, or outcome. For a simple creation tool, it is minimally adequate but leaves many gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameter meaning. It fails to compensate for the lack of schema descriptions, leaving the agent without guidance on what 'name' and 'color' represent or constraints 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 title and description clearly state 'Create a label', which is a specific verb-resource pair. Among siblings, there are get and delete label tools, so creating is distinct. The description concisely conveys the action.
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 the HTTP method and authorization class but gives no guidance on when to create a label versus using other label operations (get, delete). No context on prerequisites or when not to use this tool.
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 write operation (readOnlyHint false) and not destructive or idempotent. The description adds the authorization class (board_or_agent), which provides useful context beyond annotations. However, no further behavioral details (e.g., side effects, idempotency caveats, or return value hints) are given.
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 to the point, with no unnecessary words. It includes the endpoint and authorization class, which add value. However, it could be more information-dense given the space.
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 2 parameters, 0% schema description, and an open-world body (openWorldHint true), the description is underspecified. It does not explain the expected format of the 'body' parameter, what a skill comment is, or what the output schema contains. The agent lacks sufficient context to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for missing parameter documentation. The description does not describe any parameters: it does not explain what 'body' should contain (e.g., the comment text or its structure), nor the purpose of 'companyId' and 'skillId'. The agent has no guidance on how to construct valid input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and resource 'skill comment', which directly indicates the action and target. It is distinct from sibling tools like get, patch, and delete for skill comments, so the agent can easily differentiate.
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 on when to use this tool versus alternatives (e.g., listing, updating, or deleting comments). The description only includes an authorization class, but no context about prerequisites or preferred scenarios. The agent must infer usage solely from the tool name and title.
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 readOnlyHint=false and destructiveHint=false, which are consistent. The description adds authorization class 'board_or_agent', providing useful context. However, it does not disclose other behaviors like return value or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences. It repeats the title but includes the API endpoint and authorization class. No unnecessary information.
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 tool has 2 complex parameters (path and body) with nested objects and no parameter descriptions. The description lacks essential context about what constitutes a valid test input, leaving the agent under-informed. The presence of an output schema partially mitigates the need for return value explanation, but parameter documentation is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain parameters. It does not describe any parameter, leaving the agent to infer meaning from names alone. No details on required fields name, content, or path identifiers.
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 'Create a skill test input', which is a specific verb+resource combination. The tool name and title also align. It distinguishes from sibling tools like GET (list), PATCH (update), and DELETE.
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. It does not mention prerequisites, when not to use, or related tools for listing, updating, or deleting test inputs.
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 mutability (readOnlyHint=false) and no destruction (destructiveHint=false). The description adds the concept of a 'draft' but does not elaborate on additional behavioral traits like side effects, required permissions, or lifecycle stages.
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 concise with two short sentences. It front-loads the core action. However, the second sentence contains low-value technical detail (HTTP method and path) that could be omitted or moved.
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 that an output schema exists (not shown), the description need not detail returns. However, it lacks explanation of what constitutes a 'draft app connection' and when to use this tool, making it incomplete for a complex tool with nested parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description only hints at 'gallery input' without explaining parameters like link, name, configValues, applicationId, or credentialValues. It adds minimal meaning beyond the parameter names.
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: 'Create a draft app connection from gallery input'. It uses a specific verb and resource, matching the title. However, it does not explicitly distinguish this tool from similar siblings like the one with a similar name ending in 'c1b17b0863'.
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 does it mention prerequisites, typical use cases, 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 (readOnlyHint: false, destructiveHint: false, idempotentHint: false) indicate the tool is not read-only, not destructive, and not idempotent. The description only adds the HTTP method (POST) and auth class, without explaining side effects, data changes, or network implications. Transparency is minimal beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences. It front-loads the purpose and then adds operation details. No wasted words, but it could be more informative without sacrificing 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 the tool has two parameters, a nested body, and an output schema, the description is too brief. It fails to explain what 'refresh' entails, how it affects the issue, or what the output contains. The auth class is useful, but overall the description is incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description adds no explanation of the parameters (id, objectIds). The schema itself defines objectIds as an array of UUIDs and id as a string, but the description provides no additional meaning or context for these 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 title 'Refresh external objects mentioned by an issue' and description clearly state the action (refresh) and the resource (external objects of an issue). It distinguishes from sibling tools like pc_get_issues_by_id_external_objects and pc_get_issues_by_id_external_object_summary by specifying the POST operation for refreshing.
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 mentions the authorization class 'board_or_agent', giving some context on who can use it. However, it lacks explicit when-to-use guidance, such as when refreshing is needed vs. retrieving, or any prerequisites or alternative 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 destructiveHint=true, and the description's 'Cancel' implies mutation. However, the description adds no extra behavioral context beyond annotations, such as side effects or state requirements.
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 very short and front-loaded with the action. It is not verbose, but it could be more structured with details about parameters. Overall, it is acceptable but not ideal.
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 complexity (nested parameters, destructive action, many related siblings), the description is incomplete. It lacks context on the reason parameter, when to cancel, and output schema details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It fails to explain any parameters (path with id/interactionId, body with optional reason). This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Cancel an issue question interaction,' which is a specific verb+resource. It distinguishes from sibling tools like accept, reject, respond, and verdicts, as those have different actions.
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 accept or reject. It does not indicate prerequisites or scenarios for cancellation.
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 provide idempotentHint=true and destructiveHint=false. The description adds the authorization class ('board_or_agent') and the specific HTTP method, which are beyond annotations. However, it does not disclose other behavioral traits like effect on existing files or size limits.
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 very concise (two sentences). However, it is under-specified, lacking important parameter and usage details. Conciseness should not come at the cost of completeness.
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 complexity (2 parameters, nested objects, output schema) and 0% schema coverage, the description is severely incomplete. It fails to explain parameters, return values, or differentiate from related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description does not explain any parameters. The input schema has required objects 'body' and 'path' with nested properties, but the description provides no guidance on what these parameters mean or how to use them.
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 verb 'Upsert' clearly indicates creating or updating an agent instructions file. The title 'Upsert agent instructions file' is specific and distinguishes it from siblings like get, patch, delete for the same resource.
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 on when to use this tool over alternatives (e.g., when to use PUT vs PATCH, or this vs other instructions bundle endpoints). The description simply states the operation without usage 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 provide idempotentHint=true, readOnlyHint=false, destructiveHint=false. Description adds authorization class 'board_or_agent', which is useful. However, it does not describe side effects, whether it replaces an existing watchdog, or what happens on create vs update.
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?
Extremely concise at two sentences. However, the inclusion of the HTTP method and authorization class may be considered noise since they are implicit in the tool name and annotations. No wasted words, but could be more informative.
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 (nested parameters, output schema, relationship to other watchdog tools), the description is too sparse. It does not explain what a watchdog is, how it relates to issues, or what the response contains (output schema exists but not described). The sibling tools suggest a CRUD pattern, but no context is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fails to add any meaning to the parameters. It does not explain the role of 'agentId' or 'instructions', leaving the agent to infer from schema alone. This is insufficient for a tool with required and optional nested 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?
Description explicitly states 'Create or update an issue watchdog', providing a clear verb and resource. It distinguishes this tool from sibling tools like pc_get_issues_by_id_watchdog and pc_delete_issues_by_id_watchdog.
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 on when to create vs update, or prerequisites (e.g., issue must exist). No mention of when to use this tool over other watchdog-related tools. The description is purely functional without usage 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 mark the tool as destructive (destructiveHint=true). The description adds that it is a DELETE operation and mentions the authorization class ('board_or_agent'), providing some behavioral context beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) and front-loaded with the purpose. However, it sacrifices completeness for brevity, missing important details about parameters and usage.
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, the description does not mention what the tool returns. Required parameters (id, keyId) are not explained. For a destructive operation, more context on authorization and consequences 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 50%, but the description does not explain the parameters (id, keyId) or their roles. It only indirectly hints via the URL path. The body parameter description is vague. The description fails to compensate for the missing 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 title and description clearly state the action ('Delete') and resource ('an agent API key'). The purpose is unambiguous and distinguishes from other agent-related tools by specifying the deletion of an API key by key ID.
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 guidelines provided on when to use this tool versus alternatives, nor any prerequisites or exclusions. The description only states the operation without helping the agent decide when to invoke it.
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 adds the HTTP method and authorization requirement, but annotations already indicate destructive and idempotent behavior. The description does not elaborate on consequences or confirm idempotency, adding marginal value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, but the first sentence repeats the title. The technical details about the Paperclip operation and authorization are useful but could be more 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?
Despite having an output schema, the description does not mention return values or the effect of the operation. The optional body parameter remains unclear. The description is incomplete for a delete operation with nested objects.
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 50%, but the description does not explain the path parameters (companyId, templateId) or the body parameter beyond noting it is optional and lacks a schema. This leaves the agent with minimal understanding of expected inputs.
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 explicitly states 'Delete a skill test-run template' and provides the HTTP method and path, making the purpose clear and distinguishing it from sibling tools that perform other operations on the same resource.
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 does not provide guidance on when to use this tool versus alternatives. It only mentions the authorization class, but lacks context on prerequisites, side effects, or scenarios where deletion is appropriate.
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 adds the authorization class ('board_or_agent') and the API path, which are not in the annotations. However, the annotations already declare destructiveHint=true and idempotentHint=true, so the description does not clarify behavioral details like idempotency semantics or what happens to associated resources.
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 concise (one sentence plus two lines) but lacks structure. It is front-loaded with the purpose, but the additional lines about API path and auth class could be better integrated. It is not verbose, but it is minimal.
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 an output schema and annotations, the description is too minimal. It does not explain what happens after deletion, whether it is reversible, or what the response contains. For a destructive operation, more context 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?
The schema has 2 parameters (body optional, path.id required), but the description does not explain the 'id' parameter. The body parameter has a generic schema description, but no additional meaning is added. With 50% schema description coverage, the description should compensate but fails to.
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 tool name and description both clearly indicate 'Delete an environment'. The verb+resource are specific and distinct from sibling tools like pc_get_environments_by_id, pc_patch_environments_by_id, and pc_post_companies_by_company_id_environments.
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 (e.g., archiving or deactivating an environment). There is no mention of prerequisites, side effects, or scenarios where deletion is appropriate or not.
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 adds the authorization class ('board_or_agent') and the exact API path, which go beyond the annotations (destructiveHint=true, etc.). It correctly identifies the operation as a DELETE. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very brief (two sentences), but it repeats the title in the first sentence. It is concise but could be more structured by front-loading the key info without repetition.
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 it is a destructive operation, the description lacks warnings about irreversibility or side effects. There is no mention of return values despite an output schema existing. The auth info is helpful, but overall context is insufficient for a delete tool.
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 description does not explain any parameters. The input schema has 50% coverage (description for 'body' exists, but 'path.id' lacks explanation). The description adds no meaning to the parameters, leaving the agent to rely solely on 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 title and first sentence explicitly state 'Delete a goal', and the HTTP method 'DELETE' clarifies the action. However, it does not explicitly differentiate from sibling goal tools (e.g., pc_patch_goals_by_id) beyond the verb, so it's 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 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 pc_patch_goals_by_id or pc_post_companies_by_company_id_goals. There is no mention of prerequisites or contexts where deletion is appropriate.
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 description's mention of 'Delete' adds little new information. The authorization class ('board_or_agent') is a useful addition, but overall the description does not reveal behavioral traits beyond what annotations provide. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short but includes a redundant first sentence that repeats the title. It is front-loaded with the purpose but lacks depth. It could be more informative while maintaining 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?
Despite having an output schema, the description omits context about what happens when a document is deleted (e.g., irreversibility, cascading effects, constraints). It feels incomplete for a destructive 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 coverage is only 50%, and the description does not explain the parameters (id, key, body). The description does not add any meaning beyond the schema; it fails to compensate for the lack of parameter descriptions 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 'Delete an issue document' and specifies the HTTP method and path, making the verb and resource unambiguous. It distinguishes from sibling tools like pc_get_issues_by_id_documents and pc_put_issues_by_id_documents_by_key by indicating deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives or when not to use it. There is no mention of prerequisites, conditions, or comparison to other document operations.
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 idempotentHint=true, so the description does not need to repeat these. However, it adds the HTTP method (DELETE) and authorization class (board_or_agent), which are beyond the annotations. This provides some behavioral context but is still 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 extremely concise: two sentences conveying the purpose, HTTP method, and authorization. Every word is functional with 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 that an output schema exists and annotations cover destructive/idempotent hints, the description is minimally adequate. However, it lacks details about irreversibility, effects on related data, or prerequisites, which would improve completeness for a delete 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 50% description coverage (path parameters have no description, body says 'Optional JSON compatibility payload'). The description does not add any explanation of the parameters or their purpose, leaving the agent to infer from the schema alone.
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 verb 'Delete' and the resource 'project workspace', and includes the HTTP method and route. While the name itself is specific, the description adds clarity by explicitly stating the action, but does not differentiate from sibling tools beyond 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?
The description provides no guidance on when to use this tool versus alternatives. It lacks any mention of context, prerequisites, or exclusions, making it difficult for an agent to decide when to invoke this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds the HTTP method and authorization class but does not disclose consequences like permanent deletion or effects on related triggers. Minimal behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (two sentences), no fluff, and directly states the purpose. However, it could be more informative by adding usage guidelines or behavioral notes 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?
For a simple delete tool with one required parameter, the description is minimally adequate. It provides the basic purpose and HTTP operation. However, it lacks completeness in usage guidance and behavioral transparency, which are expected even for simple tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 50% (only body parameter described), the description adds no parameter details. It does not explain the required 'id' parameter or the optional body. The description should compensate for the gap but fails to do so.
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 title and description clearly state the tool deletes a routine trigger. The HTTP method and path are provided, distinguishing it from sibling tools like pc_patch_routine_triggers_by_id (patch) and pc_post_routine_triggers_by_id_rotate_secret (rotate). Purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives (e.g., patch or rotate). No prerequisites, side effects, or usage context are mentioned. The description only states the operation and authorization class, leaving the agent to infer 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?
The description adds the HTTP method (DELETE) and authorization class ('board'), which goes beyond the annotations (destructiveHint: true). However, it does not explain the impact of deletion (e.g., irreversible, cascade to associated secrets) or the response format. Annotations already signal destruction, so the description's added value is moderate.
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 concise with two sentences, no filler. The first sentence repeats the title but the second adds technical specifics. It is appropriately sized for a simple delete operation.
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 that an output schema exists, the description does not explain what the operation returns (e.g., success status, deleted object). It also omits critical context like whether deletion is irreversible or affects dependent resources. For a destructive operation with dependencies, this is insufficient.
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 mentions the path template with {id}, clarifying that the 'id' parameter is used in the URL. The schema documents 'path.id' as a required string, but the description adds no further detail about parameter constraints or the optional 'body' parameter. With 50% schema coverage, the description partially compensates by connecting the parameter to the endpoint.
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 deletes a secret provider configuration, with the title repeating the action. It specifies the HTTP method and path, making the resource and verb unambiguous. However, it does not differentiate from sibling tools like pc_delete_secrets_by_id or other delete operations for related resources.
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 pc_patch_secret_provider_configs_by_id for modifications. There is no mention of prerequisites, consequences, or context for deletion.
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 idempotentHint=true, so the agent knows the operation is destructive and idempotent. The description adds the HTTP method and auth class but no further behavioral context (e.g., whether the deletion is permanent, cascading effects). This is adequate given the annotations, but the description itself provides minimal extra value.
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) with no fluff, but it is under-specified. It lacks important context such as what happens on success or failure. Conciseness is achieved at the expense of completeness.
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 is destructive, the description should provide more context about the impact (e.g., what the entry is, what it affects). The output schema exists but is not shown; still, the description should explain the action's effect. Currently, it only restates the purpose and endpoint, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 2 parameters with 50% coverage; only the optional 'body' parameter has a description. The description adds no meaning to the parameters, leaving the required 'path.entryId' undocumented. The agent must infer that 'entryId' identifies the entry to delete, but no format or constraints are given.
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 tool name and title clearly state deletion of a tool access profile entry, and the description reinforces this with the HTTP DELETE method and resource path. Among siblings, there is a distinct update tool (pc_patch_tool_profile_entries_by_entry_id), so the purpose is unique 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 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 when to delete versus patch an entry. There are no prerequisites, side effects, or conditions mentioned. The only additional context is the auth class 'board', which is insufficient for an agent to decide when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false. The description adds the authorization class 'board_or_agent' and HTTP method, which is useful but not extensive. No disclosure of pagination or response behavior beyond what annotations imply.
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 very concise with two clear sentences: one for purpose and one for operation details. No redundancy, but could be slightly better structured with explicit parameter info.
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 an output schema present, return values are covered. However, given the low parameter description and no context about model profiles, the description feels incomplete. Adequate for a safe read tool but not for a complex API.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description provides zero explanation of parameters. The URL pattern implies companyId and type are required, but their meaning or acceptable values are not described. This severely hinders correct invocation.
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 'List adapter model profiles for a company', using a specific verb and resource. It distinguishes from sibling adapter tools by including the full HTTP path with 'model-profiles' endpoint, 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?
No guidance on when to use this tool vs alternatives like pc_get_companies_by_company_id_adapters_by_type_models. The description lacks context on appropriate scenarios or exclusions, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it is a GET operation requiring 'board_or_agent' authorization, which provides useful behavioral context 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but redundant: the first sentence repeats the title. The second sentence adds operational details (HTTP method, auth class). No wasted words, but could be more efficient by dropping the repetition.
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 a simple schema and output schema, the description lacks parameter explanation, scope detail (all goals vs filtered), and usage context. Incomplete for an agent to confidently invoke without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter (path.companyId) is not mentioned in the description. Schema coverage is 0%, so the description should compensate but completely fails to explain what companyId is or how to provide 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 clearly states the action 'List goals' and the resource 'in a company', matching the title. It distinguishes from sibling tools like pc_get_goals_by_id (single goal) and pc_post_companies_by_company_id_goals (create goal).
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 (e.g., pc_get_goals_by_id for a specific goal, or pc_post_companies_by_company_id_goals to create). No context on filtering, pagination, or prerequisites.
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, destructiveHint, etc. The description adds 'Authorization class: board', which is a behavioral detail not in annotations. No contradiction, but no further details on pagination or response format beyond what output schema might provide.
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 short with a front-loaded purpose, but includes redundant technical details (HTTP method) that add no value. Every sentence contributes but is not optimally concise for an AI agent.
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 simplicity, annotations cover safety, and an output schema exists, the description is minimally complete. However, it omits details like pagination or filtering, which would be helpful for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, meaning the description adds no explanation of the companyId parameter beyond the schema's type declaration. For a simple path parameter, this is minimally acceptable but fails to compensate for the coverage gap.
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 'List company members' which identifies the verb and resource. However, it does not differentiate this tool from sibling tools like pc_patch_companies_by_company_id_members_by_member_id or other member-related operations.
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 on when to use this tool versus alternatives. The description only provides the HTTP method and authorization class, lacking context for appropriate usage 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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value with 'Authorization class: board_or_agent' and the HTTP method/path. However, it does not disclose pagination, filtering, or ordering behavior. For a list operation with openWorldHint=true, more detail would be helpful.
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 very concise with two short lines and no fluff. It front-loads the purpose. However, it sacrifices completeness by omitting parameter details and usage guidance. 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 1 parameter and an output schema, the description provides the basic purpose and endpoint but lacks parameter semantics and usage context. It is minimally complete but relies on the agent inferring details from the name and schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'companyId' parameter or its format. The endpoint path implies it, but no explicit semantics are provided. This is a critical gap for a required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'List routines in a company', which is specific and distinct from sibling tools like pc_get_routines_by_id (single routine) and pc_post_companies_by_company_id_routines (create routine). The HTTP method and path further reinforce the purpose.
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. It does not mention that this tool lists all routines for a company, while other tools handle specific routines or creation. The description lacks context on prerequisites or scenarios.
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, idempotentHint=true, and openWorldHint=true. The description adds the HTTP method (GET) and authorization class, which are useful but not critical. The description does not mention pagination or filtering behavior, but the annotations cover the safety profile adequately.
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 only two lines. It wastes no words and includes the key technical detail (HTTP method and path) without any fluff. It is well-structured for quick reading.
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 simple (one parameter, read-only) and has an output schema and rich annotations. The description is minimally adequate but lacks parameter guidance and result description. Given the output schema exists, return values are not needed, but the description could be more helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should compensate for the missing parameter details. It does not explain what 'companyId' is or any constraints (e.g., format, required permissions). The schema only provides the name, so the description adds no semantic 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 'List secret provider configurations' with a specific verb and resource, and it is evident from the sibling list that this tool is distinct from related tools like pc_get_companies_by_company_id_secret_providers. However, it does not explicitly differentiate from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Authorization class: board' which hints at who can use it, but provides no guidance on when to use this tool versus alternatives (e.g., getting a single config or creating one). No explicit when-to-use or when-not-to-use information.
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, idempotentHint, and destructiveHint false, so the description adds limited behavioral context beyond the endpoint and authorization class. This is adequate but does not disclose additional behavioral traits like return value structure or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences plus a line break. It front-loads the purpose and includes the HTTP endpoint and authorization class without any fluff. Every sentence is informative.
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 is simple (read badge counts by company ID) and has an output schema (assumed to define return values), the description is fairly complete. It includes the endpoint and auth class, though it lacks explanation of what sidebar badges are or the output structure. Still, it is sufficient for a straightforward read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero description coverage, and the description does not explain the single parameter (companyId). It does not clarify what companyId represents, its format, or how it relates to the operation, leaving the parameter semantics entirely to the schema, which lacks descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The title and description clearly state 'Get sidebar badge counts', which is a specific verb and resource. However, it does not explicitly differentiate from sibling tools like pc_get_sidebar_preferences_me or other company-specific tools, leaving the purpose slightly ambiguous in context.
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 the HTTP method and authorization class but offers no guidance on when to use this tool versus alternatives. There is no mention of when not to use it or which scenarios it is designed for.
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, indicating a safe read operation. The description adds the HTTP method (GET) and endpoint path, plus authorization class. This provides useful context beyond annotations but does not disclose any additional behavioral traits like pagination, filtering, or what 'attention' means.
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 sentences capturing the purpose, HTTP method, and authorization. Every word earns its place. There is no fluff, and it is front-loaded with the core 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 simple list tool with one parameter and an output schema (so return values are documented), the description is minimally adequate. It covers the what (list) and the resource (tool apps needing attention). However, it omits context like what qualifies as 'needing attention' or how to interpret the results.
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?
There is only one parameter (companyId in path), but schema description coverage is 0%. The description does not explain what companyId represents or any constraints on it. With low coverage, the description should compensate, but it provides no parameter semantics beyond the endpoint path.
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 'List tool apps needing attention', which is a specific verb+resource combination. It clearly indicates the tool returns a list of tool apps requiring attention. However, it does not differentiate from the sibling tool 'pc_get_companies_by_company_id_attention', which might also list attention items. The purpose is clear but 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?
No guidance is provided on when to use this tool versus alternatives. For example, there is no mention of when to use this instead of 'pc_get_companies_by_company_id_attention' or other list tools. Context signals and sibling list are available, but the description itself offers no 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?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds the HTTP method (GET) and authorization class ('board'), which are useful behavioral details. However, it does not describe any other behavioral traits, so it only incrementally adds value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two short sentences. The key purpose is front-loaded, and the additional technical detail (HTTP path, auth class) is provided efficiently. No unnecessary words.
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 lacks context about what 'installable tool examples' are, how they relate to other tool management operations, and any prerequisites. Although an output schema exists, the description does not clarify the nature of the returned data. Given the tool's specificity and many siblings, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, and the description adds no explanation for the sole parameter (companyId). The agent must infer its meaning from the path pattern, which is insufficient for proper 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 explicitly states 'List installable tool examples', which is a clear verb+resource. The additional HTTP path and authorization class further clarify the purpose. It distinguishes itself from sibling tools that manage installations or gallery views.
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 exclusion criteria, and no prerequisites. It merely states what the tool does, leaving the agent to infer usage 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 readOnlyHint=true and destructiveHint=false, so the agent knows it is a safe read operation. The description adds the HTTP method and authorization class, which are useful but do not disclose additional behavioral traits 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at two sentences, with no filler. However, it could be restructured to front-load the core list action and then provide the endpoint detail. It is efficient but minimal.
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 output schema exists, return values need not be described. However, the description lacks context about what runtime slots are, why list them, or how they relate to other tools. This is a simple tool, but with many siblings, more context would aid selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no explanation of the required 'companyId' parameter (what it represents, how to obtain it). The description adds no value beyond the schema structure, leaving the agent without needed parameter context.
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 title and description clearly state 'List MCP runtime slots', which is a specific verb and resource. The description also provides the HTTP method and endpoint, making it distinct from sibling tools that stop or restart slots.
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 offers no guidance on when to use this tool versus alternatives like the stop or restart runtime slot tools, nor does it explain the purpose of listing runtime slots. No exclusion criteria or context for selection are 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 provide safety hints (readOnly, idempotent, non-destructive). The description adds the authorization class and exact API endpoint, but does not elaborate on response behavior beyond what the output schema covers.
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 (two sentences) but the first sentence repeats the title verbatim. It is front-loaded with the tool's purpose, earning a high score despite minor 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 description is adequate for a simple read tool with annotations and an output schema, but the lack of parameter explanation and usage guidance limits completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not explain the purpose of the path.id parameter, how to obtain it, or any constraints on its 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 'Get a decision training example' uses a clear verb and resource, distinguishing it from sibling tools like pc_delete_decision_training_by_id and pc_post_companies_by_company_id_decision_training.
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 the HTTP method, URL path, and authorization class but offers no guidance on when to use this tool versus alternatives, no prerequisites, and no 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 provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds the specific HTTP method (GET) and authorization class (board_or_agent), which provides context beyond annotations but doesn't disclose behavioral traits like rate limits or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences with no wasted words. The purpose is front-loaded and the structure is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter, annotations, and an output schema (not shown), the description is minimally adequate. However, it lacks context about what a feedback trace is, possible error cases, or relationship to other tools, making it barely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not explain the parameter 'traceId' beyond the schema's basic definition (required string). With low coverage, the description should compensate but adds no additional meaning.
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 'Get a feedback trace', matching the name and title. The resource (feedback trace) and action (get by trace ID) are clear, but no differentiation from sibling tools like pc_get_issues_by_id_feedback_traces.
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 on when to use this tool vs alternatives. Sibling tools like pc_get_feedback_traces_by_trace_id_bundle exist, but no explanation of the difference (e.g., single trace vs bundle).
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, idempotentHint, and destructiveHint, establishing a safe read operation. The description adds the HTTP method (GET) and public authorization class, which are useful behavioral details not captured by annotations. However, it omits error responses or behavior for invalid tokens.
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 only two sentences and an operation line. Every part is relevant, no fluff, and the core purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (though not shown), return values are likely documented elsewhere. The description covers the basic operation but lacks parameter explanation and usage context, making it minimally adequate for a simple retrieval tool.
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 one required parameter 'path.token' with no description (0% coverage). The description does not explain what the token represents or how to obtain it, leaving the agent to infer solely from the endpoint path '/api/invites/{token}/onboarding.txt'.
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 title and description clearly state 'Get onboarding instructions as plain text'. The HTTP endpoint and authorization class are provided, making the resource and format unambiguous. However, it does not explicitly differentiate itself from sibling invite tools like pc_get_invites_by_token or pc_get_invites_by_token_logo.
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 specify prerequisites, such as having a valid invite token, or indicate scenarios where other invite-related tools 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds the HTTP method (GET) and authorization class ('board_or_agent'), which provides useful behavioral context beyond the annotations. 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 very concise with two short sentences: one restating the title and one providing API implementation details. It is front-loaded with the purpose. It could be slightly more efficient by merging, but it is clear and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with one required parameter and an existing output schema, the description is adequate but not complete. It does not mention pagination, filtering, or what constitutes an 'accepted plan decomposition'. The presence of an output schema reduces the need to describe return values, but additional context about the resource would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% (no descriptions on the parameter). The description mentions the URL path with {id} but does not explain that 'id' refers to the issue ID or describe its format. It adds no semantic meaning beyond the schema, failing to compensate for the lack of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List accepted plan decompositions', which clearly indicates the verb (list) and resource (accepted plan decompositions for an issue). The name and title reinforce this, and the description includes the HTTP method. However, it does not explicitly differentiate from sibling tools like the POST version, but the purpose 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 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 mentions the authorization class but does not explain when to use this GET vs the POST version or other issue-related list tools. No explicit usage context 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?
The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the HTTP method and authorization class ('board_or_agent'), which provides useful authentication context. However, it does not disclose other behaviors such as response format, pagination, or potential error states. The added value over annotations is modest but positive.
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, consisting of two short sentences. The first sentence front-loads the core purpose, and the second adds essential technical details (HTTP method, path, authorization). Every word earns its place; there is no redundancy or fluff. This efficiency is ideal for an AI agent.
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 that the tool has one parameter and an output schema (not shown in input schema but context signals indicate output schema exists), the description is adequate but minimal. It does not describe the return value or explain the cost summary fields. While the output schema can fill that gap, the description could provide more high-level context about what the summary includes (e.g., total cost, per-resource breakdown). It is functional but not rich.
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?
There is only one required parameter: path.id (a string). The schema description coverage is 0%, so the description must compensate. The description does not mention the parameter at all; it only implies its existence via the URL path. The agent must infer that 'id' refers to the issue ID, which is reasonable from the tool name, but explicit documentation would improve clarity and reduce guesswork.
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 retrieves a cost summary for an issue, using the verb 'Get' and specifying the resource as 'issue cost summary'. It also provides the HTTP method and path, which adds clarity. However, it lacks detail on what the cost summary contains, such as currency, time period, or included cost components. Among siblings like pc_get_issues_by_id_comments or pc_get_issues_by_id_approvals, it is distinct by focusing on cost, but could be more specific to avoid 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 guidance on when to use this tool versus alternatives. It does not mention prerequisites, such as requiring an issue ID, or scenarios where this tool is appropriate. Sibling tools include many issue-related retrievals, but the description offers no context to differentiate usage, forcing the agent to infer based on 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?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds authorization class 'board_or_agent', which is useful beyond annotations, but does not elaborate on other behavioral aspects like rate limits or return structure.
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 very concise with two short sentences. However, the first sentence merely repeats the title, wasting a line. The second sentence adds technical details, but overall it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an output schema, the description should clarify what 'catalog' means and how this tool differs from similar skill-listing endpoints. It provides authorization context but lacks conceptual context. It 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?
There are no parameters, and schema coverage is 100%. The description does not need to add parameter details. A baseline of 4 is appropriate since no compensation is required.
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 states 'List catalog skills' and includes the HTTP method and path, but does not explain what 'catalog skills' means or how this differs from sibling tools like pc_get_skills_index or pc_get_skills_catalog_by_catalog_id. The verb 'List' is specific, but the resource is ambiguous.
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. There is no context about use cases or exclusions. The authorization class is mentioned but that is behavioral, not usage 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 indicate read-only, idempotent, non-destructive behavior. The description adds authorization class (board_or_agent) and the endpoint path, but lacks details like pagination handling or scope of results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise at two sentences, no filler. The title is repeated but appropriate for a short description. Structure is clean.
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?
Output schema exists, so return values are covered. However, the description fails to explain how to use filters (app, agent, limit, etc.) or note that it is a paginated list. Critical context missing for a list-with-filters tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 1 nested parameter object with 8 sub-properties, none required, and 0% schema description coverage. The description does not explain any parameter, leaving the agent to infer from property names alone.
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 title and description clearly state the action (list) and resource (tool gateway audit events), and the operation path and auth class are provided. It is easily distinguishable from sibling tools, which cover different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No context about filtering, pagination, or scenarios where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it's a write operation (readOnlyHint=false). Description adds HTTP method (PATCH) and authorization class, which provides some context beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, direct sentences. No wasted words.
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, the description lacks essential context for an update tool: no mention of which fields can be updated, side effects, or constraints. Incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameters. The agent receives no additional meaning beyond the schema property names and types.
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 'Update a goal', specifying the verb (update) and resource (goal). This distinguishes it from sibling tools like get, delete, and create goals.
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 on when to use this tool vs alternatives (e.g., when to update vs delete). No mention of prerequisites or exclusions. Only provides authorization class but no usage 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 adds the authorization class 'instance_admin' and the HTTP endpoint, which provides context beyond the annotations (readOnlyHint=false). However, it does not disclose error behaviors, return format, or side effects, leaving significant gaps.
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 concise (two short sentences) and front-loaded with the core purpose. However, it sacrifices completeness for brevity, missing parameter guidance and behavioral details that would justify longer text.
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 (not shown), the description does not mention what the tool returns upon success. For a creation tool, this is a notable omission. The description also lacks any summary of required fields or constraints, making it inadequate for an agent to understand the full context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no explanation for any of the parameters (name, description, attachmentMaxBytes, budgetMonthlyCents, defaultResponsibleUserId). With 0% schema description coverage, the agent must rely solely on the schema, which lacks descriptions. This is a critical failing.
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 a company, a specific verb+resource. It also provides the underlying HTTP method and path, distinguishing it from siblings like get, patch, and delete for companies.
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 creating companies but does not explicitly state when to use it versus alternatives like pc_post_companies_by_company_id_* (for sub-resources) or pc_patch_companies for updates. No exclusion criteria or prerequisites 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?
Annotations already indicate it is not read-only, not destructive, and not idempotent. The description adds authorization class ('board_or_agent') and confirms validation purpose, but does not detail side effects (e.g., resource creation, rate limits).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states purpose, second gives operation metadata. Front-loaded and concise with no wasted words.
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, the description does not explain return values or the nature of validation (e.g., connectivity check vs. configuration validation). It lacks context for agent decision-making, especially for a test operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain the meaning of adapterConfig, environmentId, or path parameters beyond their obvious roles in the endpoint. It adds no value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Validate' and the resource 'adapter environment access for a company', with a specific endpoint and authorization class. It distinguishes from sibling tools for getting models or detecting models.
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 on when to use this tool versus alternatives (e.g., other adapter test operations or retrieval tools). The description does not mention prerequisites or scenarios.
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 adds the authorization class and endpoint details, providing some context beyond the annotations (readOnlyHint false, destructiveHint false). However, it does not disclose key behavioral traits like whether the export is synchronous or asynchronous, or what the output is, limiting transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short, but the first sentence redundantly repeats the title. It is otherwise well-structured with the purpose front-loaded, and every sentence adds some information (endpoint and auth class). Could be improved by removing the duplicate.
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 complexity (2 params, nested objects) and the presence of sibling tools like exports_preview, the description lacks important context: it does not explain what the export produces, whether it is a file or job, or how it relates to the preview tool. The presence of an output schema is not leveraged.
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 body parameter has a description explaining it is optional and lacks a schema, which adds value. However, the required companyId parameter is undocumented in both the schema and description, so the description only partially compensates for the 50% 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 verb 'Export' and the resource 'company data', providing a clear purpose. However, it does not differentiate from the sibling tool pc_post_companies_by_company_id_exports_preview, so it loses a point for lacking 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?
The description provides no guidance on when to use this tool vs alternatives like preview or import tools. It only gives technical details (HTTP method, path, authorization class) but no contextual usage advice.
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 readOnlyHint=false and destructiveHint=false, so it's a write operation but not destructive. The description adds the operation type (POST) and authorization class 'board', which is useful. However, it does not explain potential side effects, output behavior, or whether it modifies state. Beyond annotations, it offers limited 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (three lines) but includes redundant repetition of the title. It conveys the operation and auth class efficiently, but the title repeat wastes space. Could be more concise by omitting the repeated title.
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 two parameters and an output schema, the description is incomplete. It does not explain what the smoke checks do, what the required parameters (companyId, id) refer to, or what the response contains. The output schema existence is not leveraged. The description lacks sufficient context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%; only the body parameter has a description (noting it is optional and lacks a schema). The description does not explain the 'path' parameters (companyId, id) or their roles. No additional meaning is added beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Run tool example governance smoke checks' on a specific resource (tool examples). It distinguishes from siblings like 'pc_get_companies_by_company_id_tools_examples' (list) and 'pc_post_companies_by_company_id_tools_examples_by_id_install' (install). The inclusion of the HTTP method and path reinforces the purpose.
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 on when to use this tool versus alternatives. The description does not explain the context for running smoke checks (e.g., after installation, before deployment) or when not to use it. Sibling tools are not 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 already provide readOnlyHint=false and destructiveHint=false. The description adds the authorization class (instance_admin) but does not disclose side effects, asynchronous nature, or potential impact. It meets baseline but adds minimal value.
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 sentences: one for action, one for implementation details. Efficient and front-loaded. Could be slightly more informative without adding length.
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?
Lacks context about what happens after triggering (e.g., returns job ID, is async). Output schema exists but description doesn't leverage it. For a mutation tool, more completeness 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?
Only one optional parameter (body) with no schema. Schema coverage is 100%, so the schema documents it. Description does not explain when body is needed. Baseline score is appropriate.
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 it triggers a database backup, matching the name and title. No sibling tool is similar, so differentiation is not needed. However, it could benefit from specifying what type of backup (e.g., full) or scope.
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 on when to use this tool versus alternatives. Mentions authorization class but no context about preconditions 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is not read-only (readOnlyHint=false). The description adds the authorization class ('board') and hints at an action ('run auto-recovery') but does not explain side effects, such as whether the recovery is synchronous or if it modifies state, beyond what annotations imply.
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 concise, consisting of two short sentences that convey the action and technical details. No extraneous information, but the second sentence could be integrated more smoothly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and annotations, the description provides the operation and authorization class. However, it lacks context about the recovery process (e.g., whether it's asynchronous, what triggers it, or potential impacts), leaving the agent with only a high-level understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description does not mention the 'lookbackHours' parameter at all. The agent must rely solely on the schema's name and constraints, which may not be sufficient to understand its purpose (e.g., hours to look back for recovery candidates).
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 'Run issue graph liveness auto-recovery' and includes the HTTP method and path, making the tool's purpose specific and distinguishable from its siblings (e.g., the similar named sibling is differentiated by the full path).
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 does it mention prerequisites, context, or exclusions. The agent is left to infer usage from the tool name alone.
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 adds the authorization class ('board_or_agent') beyond what annotations provide. Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description does not contradict them. It correctly identifies the operation as a POST (write). No additional behavioral details like side effects or response structure are given, but the auth info is useful.
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 only two sentences, which is concise. However, the first sentence is redundant with the title. The second sentence provides the endpoint and auth class, which is useful. There is no fluff, but the redundancy slightly reduces 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 the tool's complexity (nested objects, 2 required parameters, output schema exists), the description is very minimal. It does not explain parameter requirements, the response structure (though output schema exists but is not detailed), or any constraints (e.g., thread must exist, comment body is required). This leaves significant gaps for an AI agent to correctly invoke the tool.
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 0% description coverage, yet the description does not explain any parameters. Parameter names like 'id', 'key', 'threadId', and 'body' are somewhat self-explanatory (e.g., path fields identify resources, body contains comment text), but the description offers no clarification. For low schema coverage, the description should compensate but fails to do so.
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 'Add a document annotation comment' and provides the HTTP endpoint and authorization class, clearly identifying the verb and resource. However, it does not explicitly differentiate from sibling tools like pc_post_issues_by_id_documents_by_key_annotations (which creates a thread) or pc_patch_issues_by_id_documents_by_key_annotations_by_thread_id (which updates a thread). The purpose is clear but 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?
No guidance is provided on when to use this tool versus alternatives, such as when a comment should be added versus creating a new annotation thread. No prerequisites (e.g., existence of annotation thread) are mentioned, nor are any conditions for not using it. The description is silent on 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?
Annotations already indicate this is not read-only, not idempotent, and not destructive. The description adds no additional behavioral context, such as side effects (e.g., redirecting the user) or the fact that OAuth sign-in is an interactive flow.
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 (two sentences plus operation line) and front-loaded with the main purpose. It is concise without unnecessary words.
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 two parameters, the description is too minimal for an OAuth start flow. It lacks explanation of the OAuth process, what triggers the sign-in, expected output, and any required user interaction.
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 both parameters adequately: 'body' has a description, and 'path.connectionId' is a simple string. The description does not add extra meaning beyond the schema, 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 action ('Start OAuth sign-in') and the resource ('tool connection'). It is specific and distinguishable from the many sibling tools, as no other tool has a similar verb-resource combination.
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 only mentions the authorization class ('board') but does not explain the context or prerequisites for starting an OAuth sign-in.
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 idempotentHint=true. The description adds authorization class ('board_or_agent'), providing extra context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise at two sentences, no wasted words. Could be slightly more structured (e.g., bullet points) but is acceptable for a simple delete operation.
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?
Minimal context beyond operation. No mention of prerequisites, side effects, or return values (though output schema exists). For a destructive tool, more contextual completeness would help.
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 only 50% (path.id described, body only noted as optional). Description does not explain parameters further; lacks detail on what 'body' expects despite being optional.
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 ('Delete') and the resource ('agent instructions file'), and the HTTP operation reinforces this. It distinguishes from sibling tools like pc_delete_agents_by_id which deletes the entire agent.
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 on when to use this tool vs. alternatives (e.g., pc_patch_agents_by_id_instructions_bundle for modifications). No prerequisites or exclusions 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 already convey destructive and idempotent behavior. The description adds the HTTP method (DELETE) and authorization class ('board'), providing some additional context. However, it does not explain side effects or irreversible nature beyond annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences), with the purpose stated first. It is concise but sacrifices completeness for brevity. No extraneous information.
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 lacks critical context for a destructive tool: no mention of irreversibility, required permissions beyond 'board' class, or post-revocation effects. The output schema exists but is not referenced, and the optional body parameter is unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 50% schema coverage, the description adds minimal parameter meaning beyond the schema. It mentions '{keyId}' in the endpoint but does not explain what keyId represents or the optional 'body' parameter. No parameter descriptions are provided in the text.
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 title and first sentence clearly state 'Revoke a board API key,' specifying the verb (revoke) and resource (board API key). This distinguishes it from sibling tools like pc_get_board_api_keys (list) and pc_post_board_api_keys (create).
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 on when to use this tool vs. alternatives. The description does not mention prerequisites, context, or exclusions. The agent must infer from the name and endpoint 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?
Annotations already indicate destructiveHint=true, so the description's mention of 'Delete' is consistent. It adds the authorization class 'board_or_agent', which is useful. However, it does not describe any side effects or requirements (e.g., skill not in use).
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 brief (two sentences) and free of extraneous detail. It front-loads the core action. However, the second sentence could be formatted more cleanly.
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 annotations and an output schema, the description lacks important context for a destructive operation, such as idempotency behavior (what happens if the skill is already deleted) or prerequisite conditions. It does not elaborate on the deletion's effects.
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 description does not mention any parameters. The schema has 50% coverage: the 'body' parameter has a description in the schema, but the 'path' sub-properties (companyId, skillId) lack descriptions. The description adds no meaning to these 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 clearly states the verb 'Delete' and the resource 'a company skill', making the action immediately understandable. It also includes the HTTP method and authorization class for additional context.
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 creating, updating, or listing skills. The sibling tools list includes related operations, but the description does not differentiate them.
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 destructiveHint=true and idempotentHint=true. The description adds that it uses DELETE method and 'Authorization class: board', providing some behavioral context. However, it does not elaborate on the consequences of deletion (e.g., irreversible removal of associated secrets) beyond what annotations imply. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with two short sentences and no redundant information. It is front-loaded with the key action. However, it could be more structured (e.g., bullet points) and still remain concise. The brevity sacrifices some helpful 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 is destructive (deletion of a user secret definition), the description lacks important context: it does not mention that the operation is irreversible, requires specific permissions, or has side effects (e.g., invalidating secrets). An output schema exists but is not referenced. The description is too minimal to be fully complete for an AI agent.
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 description does not explain any parameters. Input schema coverage is 50%: the optional 'body' parameter has a description, but the required 'path' and its nested 'companyId' and 'definitionId' have no schema descriptions. The description adds no semantic value, leaving the agent to infer from parameter names alone.
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 explicitly states 'Delete a user secret definition', matching the tool name and title. It specifies the HTTP method and endpoint, clearly identifying the action and resource. This distinguishes it from sibling tools like 'pc_delete_companies_by_company_id' (delete a company) and 'pc_delete_secrets_by_id' (delete a secret).
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 when to delete vs. patch a definition. There is no mention of prerequisites, required permissions, or context. It simply states the operation without usage instructions.
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 provide readOnlyHint false, destructiveHint true, etc. The description adds the HTTP method and path, but does not elaborate on side effects or state changes 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 description is short and front-loaded with the main purpose. It is efficient, though could benefit from a small structured breakdown.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple operation, the description is adequate but minimal. It does not explain response format or prerequisites, missing an opportunity given an output schema exists.
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 50%, but the tool description does not mention any parameters. The body and path are left unexplained, failing to compensate for low 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 and title clearly state the tool marks an issue as unread. It differentiates from sibling tools like pc_post_issues_by_id_read (mark as read), but could be more specific about the effect.
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 mentions the authorization class (board_or_agent), giving context on who can use it. However, it lacks explicit when-to-use or when-not-to-use guidance relative to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true. The description adds the HTTP method (DELETE) and authorization class ('board_or_agent'), which are useful but do not significantly expand on behavioral traits beyond what annotations indicate.
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 very concise, using only two sentences. It is efficient and front-loaded, but it could be slightly more structured by separating the purpose, HTTP method, and authorization. Overall, it earns its place with no fluff.
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 destructive nature, the description is incomplete. It does not mention what happens upon deletion (e.g., irreversibility, cascading effects), error scenarios, or the meaning of the path parameter. The output schema exists but does not excuse missing contextual details about the operation's effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 50% schema description coverage, the description adds no parameter-specific information. The body parameter is described in the schema, but the required path.id lacks any description in both schema and description text. The description does not compensate for this gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Delete') and resource ('a work product'). It is a specific verb-resource pair that distinguishes it from siblings. The inclusion of the HTTP method and authorization class reinforces 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, such as when not to delete, prerequisites, or conditions. It simply describes the operation without contextual usage hints.
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, idempotentHint, and destructiveHint, indicating a safe read operation. The description adds the authorization class 'board_or_agent', providing slightly more behavioral context, but omits details like pagination or ordering.
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 two short sentences. The first repeats the title, the second provides the HTTP operation and authorization class, with no unnecessary 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?
For a simple list operation with one parameter and an output schema, the description is adequate but lacks explanation of what config revisions are or how to interpret results. It does not mention that the output schema provides return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the 'path.id' parameter, leaving its purpose implicit. With 0% schema description coverage, the description should compensate but fails to clarify that the id refers to the agent whose revisions are listed.
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 title and description clearly state the tool lists agent config revisions, with a specific verb 'List' and resource 'agent config revisions'. The name and path distinguish it from siblings like getting a specific revision.
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 getting a specific revision or rolling back. Only the HTTP method and authorization class are mentioned, but no context on use cases.
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, idempotentHint, etc. The description adds the authorization class 'board_or_agent' and the HTTP method/endpoint, which provides some behavioral context. However, beyond that, no additional behavioral traits are disclosed.
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 concise, front-loading the purpose in the first sentence. The second sentence about Paperclip operation adds technical detail that may not be essential but does not detract heavily.
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 no parameters and an output schema available, the description adequately conveys its purpose and key behavioral traits. It could be slightly improved by noting that it returns all assigned inbox items, but it is generally 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 has zero parameters, and schema coverage is 100%. The description does not need to add parameter info, and baseline is 3 due to high 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 verb 'Get' and resource 'current agent assigned inbox items'. It is specific and distinct from most sibling tools, but does not explicitly differentiate from the similar sibling pc_get_agents_me_inbox_lite.
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 exclusions, and no context about prerequisites or typical use cases.
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 readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that it is a GET operation and requires 'board_or_agent' authorization, which supplements the annotations but does not significantly go 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) but repeats the title in the first sentence. It is concise but front-loading could be improved by stating the purpose immediately rather than repeating the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and an output schema, the description is minimal yet adequate. It conveys the basic purpose and HTTP method, but lacks details on the output structure or potential prerequisites, though annotations cover safety.
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 single required parameter 'path.id' is not described in the schema or the description. With 0% schema description coverage, the description should clarify that 'id' refers to the approval ID, but it does not.
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 'List issues linked to an approval', using a specific verb and resource. This purpose is distinct from sibling tools like pc_get_issues_by_id which lists all issues, not those linked to an approval.
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 does it mention any exclusions. Sibling tools include many approval-related operations, but no contextual usage hints are given.
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 and idempotentHint=true. The description adds the HTTP method (GET) and endpoint path, as well as the authorization class ('board_or_agent'), which provides useful behavioral context 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise—two short sentences. The first line repeats the title but the second line provides valuable HTTP endpoint and auth info. No unnecessary words, but could be slightly more structured (e.g., separate sections).
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 are covered. The description provides the endpoint and auth class, but fails to explain the two required parameters (companyId and kind) or differentiate from sibling tools. For a simple listing tool, this is adequate but 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?
Schema description coverage is 0%, so the description should explain parameters but does not. It only hints at 'item kind' without explicitly naming the 'kind' parameter or its enum values (routine, skill). The companyId parameter is not mentioned at all.
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 'List folders for a company item kind', which clearly identifies the verb (list) and resource (folders). The title reinforces this. However, it does not explicitly differentiate from sibling folder tools like create or delete, though the verb 'list' implies read-only.
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 pc_post_companies_by_company_id_folders (create) or pc_delete_companies_by_company_id_folders_by_folder_id (delete). The agent must infer from 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 readOnlyHint=true and destructiveHint=false, so the description adds limited value. It does state the authorization class ('board'), which is minor additional context. 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 extremely concise with two sentences. The first sentence states the purpose, the second adds technical details. No wasted words; front-loaded with the core 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?
Given the tool's simplicity (one parameter, output schema exists), the description is minimally adequate. It identifies the resource and action but does not describe the output or any additional behavior. The title and description together barely meet the bar for context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for its single parameter (companyId). The description provides no information about the parameter, its format, or acceptable values. For a tool with only one parameter, this is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The title and description clearly state 'List current user's resource memberships', with a specific verb and resource. The description adds the HTTP method and path, distinguishing this read operation from the PUT siblings for resource memberships.
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 does not provide any guidance on when to use this tool versus alternatives, lacks prerequisites, and has no when-not or explicit context. The agent is left to infer usage from the name and title.
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 adds that this is a GET operation and returns the latest document and generation state, reinforcing the readOnlyHint and idempotentHint from annotations. No contradictions. However, it adds little beyond what annotations already imply, so transparency is adequate but not enhanced significantly.
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 (two sentences), front-loads the purpose, and provides the HTTP method and authorization. It is efficient and avoids unnecessary words, earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers basic purpose and path, but given the complexity (nested object with three parameters), it lacks parameter explanations. The presence of an output schema reduces the need to describe return values, but the missing parameter context and lack of sibling differentiation make it minimally adequate.
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 0% description coverage, and the tool description does not explain the purpose or constraints of companyId, scopeKind, or slotKey. The description only shows the path template without parameter semantics, leaving the agent to guess their meaning.
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 it retrieves a summary slot with its latest document and generation state. It specifies the HTTP verb and path. However, it does not differentiate between this GET and the sibling GET on summary slots (pc_get_companies_by_company_id_summary_slots_by_scope_20820b2eee), so clarity is good 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 the HTTP method and path, implying usage for retrieving a summary slot. It also mentions authorization class. However, it lacks explicit guidance on when to use this GET versus other summary slot operations (PUT, POST, other GET), leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true, so the safety profile is clear. The description adds useful behavioral context: it specifies the HTTP method (GET) and authorization class ('board'), which helps the agent understand the operation's nature and access requirements. 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: two sentences, both front-loaded. The first sentence gives the purpose, and the second provides the HTTP operation and authorization. Every word adds value, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with one parameter, the description covers the action, resource, and operation details. However, with 0% schema coverage, it should provide at least a brief explanation of the 'companyId' parameter. The output schema exists, so return values are covered elsewhere, but the input is not. This is a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the schema does not describe parameters. The description does not add any parameter semantics; it does not explain what 'companyId' represents or what the 'path' structure is. With 0% coverage, the description must compensate, but it fails to do so.
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 title and description clearly state the action 'List' and the resource 'tool connections'. Among the many sibling tools, there are other tool-related endpoints (e.g., create, update, delete), but this one is uniquely for listing connections, so it distinguishes itself. However, it does not explain what 'tool connections' are, which could be slightly ambiguous.
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 prerequisites, typical use cases, or when not to use it. The annotations indicate read-only and idempotent, but explicit usage guidelines are missing.
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 specifies the HTTP method (GET) and authorization class (board_or_agent), adding value beyond annotations. Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, which align with the 'Get' verb. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences plus a line for operation and auth. It front-loads the purpose and includes necessary details without excess. Could be slightly tighter by removing the repeated title line.
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 adds the auth class, which is helpful for authorization context. With annotations and output schema present, it is adequate but lacks details on return value or error handling. Meets minimum viability for a simple read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning no parameter descriptions exist in the schema. The description does not explain the meaning or format of companyId or userSlug, leaving the agent without guidance. A higher score would require explicit parameter 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 the tool retrieves a user profile within a company, with a specific verb and resource. It is distinguishable from related user tools like user_directory or members, though not explicitly contrasted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 pc_get_companies_by_company_id_user_directory or pc_get_companies_by_company_id_members. The agent has no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the authorization class 'board_or_agent' and the exact HTTP method and path, providing additional actionable context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with two substantive sentences plus endpoint details. Front-loaded with the core purpose. Could be slightly more structured with parameter info, but overall efficient.
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 presence of an output schema (context signal), the description need not detail return values. However, the lack of parameter semantics and usage guidelines leaves a significant gap for a tool with only one input. The agent is underinformed about the required companyId.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not elaborate on the 'companyId' parameter at all. It neither explains its format, source, nor relationship to the operation, leaving the agent without necessary parameter context.
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 'Get the current user's inbox agent policy' with verb and specific resource. The inclusion of the HTTP method and path further clarifies the operation. The 'current user' qualifier distinguishes it from similar tools for other users.
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 on when to use this tool versus alternatives like the PUT counterpart or other user policy tools. The agent must infer usage context from the tool name and path alone.
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 the tool is read-only, idempotent, and non-destructive. The description adds value by specifying the HTTP method (GET) and authorization class ('board_or_agent'), which are useful behavioral details beyond the annotations. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences. It is front-loaded with the purpose. However, it could include more contextual information without becoming overly 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 description is minimal and does not explain what a heartbeat run is or how it fits into the system. While an output schema exists, the description lacks context that would help an agent understand the tool's role among many sibling tools.
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 0% description coverage, meaning no parameter descriptions. The tool description does not explain the runId parameter beyond its name, failing to add meaning beyond the schema. Given low schema coverage, more compensation was needed.
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 'Get a heartbeat run', which is a specific verb+resource combination. It is distinguishable from sibling tools like pc_get_heartbeat_runs_by_run_id_issues by focusing on the run itself, but it does not explicitly differentiate from the list tool pc_get_companies_by_company_id_heartbeat_runs.
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. There is no mention of prerequisites, when not to use it, or comparisons with related tools such as the list heartbeat runs tool.
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 agent knows this is a safe, read-only operation. The description adds the endpoint path and authorization class, which provides some context but does not disclose additional behavioral traits beyond what annotations already cover. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief, consisting of three short sentences. The first sentence repeats the title, which is slightly redundant, but overall there is no wasted content. The structure is clear and front-loaded with the core purpose. It earns a high score for conciseness, though the redundancy prevents a perfect 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?
Although the tool has an output schema (so return values need not be explained) and annotations cover safety, the description lacks critical context: it does not describe what an 'issue comment' is, how to obtain the required IDs, or any special behavior (e.g., auth requirements beyond the annotation). The missing parameter semantics further detract from completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, meaning no parameter descriptions in the input schema. The description fails to compensate by explaining what the 'id' and 'commentId' path parameters represent. It merely includes them as placeholders in the URL template. This omission leaves the agent without necessary semantic context for the 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 clearly states 'Get a single issue comment', which is a specific verb ('Get') and resource ('single issue comment'). The tool name and title reinforce this, and it distinguishes itself from siblings like pc_get_issues_by_id_comments (list) and pc_delete_issues_by_id_comments_by_comment_id (delete) by focusing on a single entity.
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 provide guidance on when to use this tool versus alternatives. While the name and title imply it is for retrieving a specific comment, there is no mention of when to prefer this over listing comments or other related operations. The inclusion of the endpoint and authorization class is informative but does not address usage selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds the authorization class ('board_or_agent'), which is useful context. However, no further behavioral traits (e.g., pagination, output format) are described.
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 concise at two sentences, but the first sentence merely restates the title. The second sentence adds the HTTP method and authorization class. It is not wasteful, but could be more efficient by combining the information.
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 that an output schema exists, the description does not need to explain return values. However, for a list operation, it lacks any mention of sorting, filtering, or pagination. The authorization class is a useful addition, but overall the description is minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description does not explain what 'id' and 'key' represent. It is inferred from context that 'id' is an issue ID and 'key' is a document key, but this is not explicit. The description fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List document annotation threads', which is a specific verb+resource. The sibling tools include a POST for creation and a GET with thread_id for a specific thread, so it distinguishes itself by the 'List' verb and the absence of a thread_id parameter.
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., the POST version or the GET for a specific thread). There is no 'when to use' or 'when not to use' advice.
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, idempotentHint, and destructiveHint flags, which clearly indicate a safe read operation. The description adds the HTTP method and authorization class, which are useful but not critical 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description consists of only two sentences, but the first sentence is a verbatim repeat of the title. While concise, it wastes space. The second sentence provides the HTTP operation and auth class, which is valuable.
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 simple with annotations and an output schema, but the description does not explain what the status response contains or any specifics about local folders. It is minimally complete for an AI agent but lacks helpful elaboration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no inline parameter descriptions. The description does not add any meaning to the three parameters (pluginId, companyId, folderKey). The parameters are self-explanatory but the description should have clarified their roles if the schema lacks details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the status of a plugin's local folder, using specific verbs and resource identifiers. It distinguishes from siblings by focusing on status retrieval, and the HTTP path is provided, leaving no 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 on when to use this tool versus alternatives such as other plugin-related tools. No prerequisites, contexts, or exclusions are mentioned, leaving the agent to infer 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 indicate readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds the HTTP method (GET) and authorization class ('board'), which provide minor behavioral context beyond annotations. However, it does not disclose pagination, response structure, or performance implications.
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 (two lines) and front-loads the core purpose. The inclusion of the HTTP endpoint and auth class provides useful technical context without verbosity. However, it could be slightly more informative without sacrificing brevity.
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 simplicity (no parameters, existing output schema, rich annotations), the description is adequate but lacks nuance. It does not explain what 'example plugins' means, whether they are from a catalog or installed, or how the output is structured. While the annotations cover safety and idempotency, additional context about the return format 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 tool has zero parameters and schema coverage is 100%, so the schema already fully documents the interface. The description adds no parameter-specific information beyond what the schema provides, which is acceptable given the absence of 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 'List example plugins', which is a specific verb+resource combination. However, it does not differentiate from sibling tools like pc_get_plugins or pc_get_plugins_tools, which also list plugin-related information. The additional HTTP route and auth class provide context but don't clarify the unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 pc_get_plugins (for all plugins) or pc_get_plugins_tools (for plugin tools). The description omits any context on prerequisites, scope, or filtering, leaving the agent to infer 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, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds the HTTP method (GET) and authorization class (board_or_agent), which is useful 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?
The description is extremely concise with two sentences. The first sentence immediately states the core function, and the second provides operational details. Every word is necessary and there is 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?
Given the simplicity of the tool (read-only list), the existence of an output schema, and the annotations covering behavioral traits, the description is sufficiently complete for an agent to understand the basic operation. However, it could mention that it returns a list of revisions or version history, though the output schema may compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage for the single parameter (id). The description does not explain what the 'id' represents (e.g., routine ID) or provide any additional context beyond the schema structure. With only one parameter, the description should at least hint at its meaning.
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 verb 'List' and resource 'routine revisions', making the primary purpose unambiguous. However, it does not differentiate from sibling tools like pc_get_routines_by_id or pc_get_routines_by_id_runs, which could cause confusion for an AI agent selecting among similar 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?
There is no guidance on when to use this tool versus alternatives. The description only states what it does and provides an HTTP route and authorization class, but fails to specify context, prerequisites, or exclusion criteria.
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 declare readOnlyHint, idempotentHint, and destructiveHint false, which convey safety and idempotency. The description adds the HTTP method (GET) and authorization class ('board_or_agent'), which are useful behavioral details beyond what annotations provide. It does not mention pagination or response format, but output schema exists to cover that.
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 only two sentences. The first sentence clearly states the purpose, and the second provides the HTTP endpoint and authorization. Every sentence adds value without 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?
Given the tool's complexity (listing runs) and the existence of an output schema, the description still lacks important context such as what information the runs contain, typical use cases, pagination, or ordering. The minimal information leaves the agent with unanswered questions about how to interpret the results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning the description must explain the parameters. However, the description does not mention the required parameter (the routine ID) at all. The agent must deduce that the 'id' in the path is the routine identifier from the tool name and context. This lack of explanation is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List runs for a routine'. The verb 'list' and resource 'runs' are specific. It distinguishes from sibling tools like pc_post_routines_by_id_run (which creates a run) and pc_get_routines_by_id (which gets the routine itself). However, it does not elaborate on what 'runs' are, which is a minor gap.
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 when to list all runs vs. retrieve a specific run or create a new run. There is no mention of prerequisites, common filters, or data retrieval patterns. The agent must infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds specific HTTP method (GET) and authorization class ('board'), which are not in annotations, providing helpful behavioral context beyond the structured data.
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 sentences) with the primary purpose front-loaded. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (not provided), the description is minimally adequate for a simple read operation. However, it does not explain what the catalog contains or any prerequisites (e.g., connection must exist), leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain the required 'connectionId' parameter. No parameter semantics are added, leaving the agent with no guidance on how to construct the input.
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 ('List') and the resource ('a tool connection catalog'), distinguishing it from sibling tools like usage or grants. However, 'catalog' could be ambiguous without context, slightly reducing 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?
No guidance is provided on when to use this tool versus alternatives. The description does not mention exclusions, prerequisites, or contrast with sibling 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 declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds the HTTP method (GET) and authorization class ('board'), which provides some behavioral context. However, it does not discuss error conditions (e.g., invalid connectionId) or return value structure (though output schema exists).
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 very concise, using two sentences. The first repeats the title (acceptable), and the second provides HTTP details. No unnecessary words. However, the first sentence could be more informative rather than repeating the title.
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 (single parameter, output schema exists, annotations cover safety), the description is fairly complete. It states the purpose and provides the HTTP path and auth class. It lacks some context about what the output represents, but the output schema likely covers that. Overall, it meets the needs for a straightforward read 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 one parameter (path object with connectionId) with 0% schema description coverage. The description compensates slightly by showing the URL pattern, which implies connectionId is required and used as a path parameter. This adds modest meaning beyond the raw schema, but does not explain the parameter structure or validation rules.
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 ('List tool connection grants') and the resource. The title reinforces this. However, it does not explicitly distinguish from sibling tools like pc_post_tool_connections_by_connection_id_grants_installations or pc_delete_tool_connections_by_connection_id_grants_by_grant_id, though the verb 'list' implies a read-only 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 explicit guidance on when to use this tool versus alternatives. The description does not mention when not to use it, prerequisites, or contrast with other grant-related tools. This is a notable gap, especially given the large number of 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?
Annotations indicate readOnlyHint=false and destructiveHint=false, which is consistent with an update operation. However, the description adds minimal behavioral context beyond the HTTP method and authorization. It does not disclose that this is a partial update (PATCH), what fields can be updated, or any side effects. The body parameter is undocumented, leaving the agent uncertain about how to construct the request.
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 concise with two sentences. The first sentence reiterates the title. The second adds HTTP method and authorization class. It is efficient but could incorporate more helpful details 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 the tool is part of a CRUD suite for company skills and has an output schema, the description lacks necessary context. It does not mention that it is a partial update (PATCH), what the response contains, or prerequisites (e.g., skill must exist). The agent is left to infer from sibling tool names.
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 50% (body parameter lacks a description). The description does not explain the purpose or format of companyId, skillId, or the optional body. It adds no semantic value beyond what the input schema 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?
The title and description clearly state 'Update a company skill,' with a specific verb and resource. This distinguishes it from sibling tools like POST (create), GET (read), and DELETE (delete) for company skills.
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 via the HTTP method PATCH (update), but it does not explicitly state when to use this tool versus alternatives (e.g., POST for create, DELETE for delete). No when-not-to-use guidance is 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 provide some base info (not read-only, not destructive). The description adds the HTTP method (POST) and authorization class, but does not clarify if the 'fetch' operation has side effects or permissions required beyond the auth class. The word 'Fetch' contrasts with POST, causing mild confusion.
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?
Very concise (2 sentences plus extra line). No wasted words, but the structure could be improved by separating purpose from technical details like HTTP method and auth class.
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, the description is incomplete: it does not explain what the 'key' parameter is, how to obtain it, or what 'current agent run' means for parameter input. The tool has two parameters with insufficient coverage.
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 50%; only the body parameter is described briefly. The key parameter – critical for fetching a secret – is not described in either the schema or the description. The description adds no parameter semantics 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 'Fetch one secret value for the current agent run', specifying the verb (Fetch), resource (secret value), and scope (current agent run). This distinguishes it from sibling tools like pc_get_agents_me_secrets that list secrets.
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 on when to use this tool versus alternatives. It does not mention when-not to use it or direct to any sibling tool for listing secrets. The description is purely operational.
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-destructive, non-idempotent, and open-world hints. The description adds the authorization requirement ('board') but does not disclose side effects (e.g., whether it creates an admin or modifies state) or error conditions. The added value is marginal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three brief sentences, front-loaded with the core purpose. No unnecessary words; every sentence delivers essential information concisely.
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, the description lacks critical context for a bootstrapping operation: prerequisites (e.g., unclaimed instance), success behavior, failure modes, and idempotency implications. This omission leaves the agent with insufficient understanding to use the tool safely.
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 description mirrors the schema's parameter info ('Optional JSON compatibility payload. The source OpenAPI operation does not declare a request schema.'). It adds no new 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (claim first instance admin) and the resource (browser session), with the HTTP method and path. It distinguishes the tool's specific bootstrap purpose but does not compare with sibling tools, which is acceptable given the unique endpoint.
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 the authorization class ('board') but offers no explicit guidance on when to use this tool versus alternatives, nor any context for prerequisites or exclusions. The usage scenario is implied but not clearly defined.
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. The description adds the authorization class but does not disclose side effects (e.g., immediate session invalidation, need to re-authenticate).
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?
Very concise: two lines with the action and endpoint. Front-loaded and no wasted words. However, it could include more context 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?
With single optional parameter and annotations present, the description covers the basics. But it lacks context on post-revocation behavior or when revocation is appropriate.
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% (only one optional 'body' parameter). The schema description already explains the parameter; the description adds no additional meaning.
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 'Revoke current CLI auth session' with the specific API endpoint and authorization class. This distinguishes it from sibling tools like pc_get_cli_auth_me or pc_post_cli_auth_challenges.
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 on when to use this tool versus alternatives (e.g., other auth revocation tools). The description lacks context about prerequisites or typical use cases.
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 openWorldHint=true, implying unknown side effects, but the description does not disclose any such effects. It only explains the input format anomaly. No mention of post-upload behavior, rate limits, or consequences, leaving the agent underinformed.
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 concise (three sentences) and includes key details: operation action, endpoint, auth class, and input note. It is front-loaded with the main verb. Minor improvement could be structural formatting, but no extraneous content.
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 presence of an output schema (not described), 3 parameters, nested objects, and openWorldHint, the description does not cover output format, error conditions, or side effects. It provides essential input details but is incomplete for a full understanding of tool 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 description adds context for the multipart parameter (explaining it as a compatibility fallback for the omitted upload body), which is beyond the schema. However, it does not elaborate on the path parameters or the body parameter's usage, leaving gaps that the schema's 67% coverage partially fills.
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 'Upload an attachment to an issue', using a specific verb and resource. The action is distinct from sibling tools like list, get, and delete attachments. The endpoint and HTTP method are provided, reinforcing the upload purpose.
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. The description mentions authorization class 'board_or_agent' as a prerequisite but does not suggest when to prefer this over other attachment operations 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a non-read-only, non-destructive write operation. The description adds context about the Paperclip operation and multipart compatibility, but does not disclose behavioral traits like error handling, idempotency implications, or side effects beyond the annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three sentences) and front-loads the purpose. There is no unnecessary verbosity, though the technical phrasing could be clearer for non-specialist agents.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic purpose and technical details (OpenAPI, multipart). However, it omits important context such as file size limits, allowed formats, whether the operation replaces an existing logo, or what the output schema contains. For a file upload tool, these are relevant 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 67%, and the description adds minimal value beyond the schema: it notes that the upload body was omitted in the source spec and that this gateway provides multipart compatibility. This information is already present in the parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The title and description clearly state 'Upload company logo', specifying the action and resource. It is distinct from siblings as there is no other logo upload tool. However, the description does not explicitly differentiate from potentially related branding 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 mentions authorization class but provides no guidance on when to use this tool versus alternatives, nor any conditions or prerequisites for 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 indicate this is a non-read-only, non-destructive mutation. The description adds the authorization class ('board') and confirms the HTTP method. However, it does not explain side effects (e.g., whether the profile still exists after unbinding) or any prerequisites. It adds some value but not substantial 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 a single sentence followed by a concise technical detail (endpoint and auth class). No wasted words, but the structure could be improved by separating the operational detail from the primary explanation. Still efficient for the purpose.
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 nested input schema, the description lacks essential context like prerequisites (e.g., the profile must exist and be bound to a target), the effect of the unbind operation, and any required permissions. Schema coverage is zero, and the description does not fill the gap, leaving the agent with incomplete understanding.
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 zero property descriptions (0% coverage), yet the description does not explain any parameter meanings. It mentions only the target types in the title, missing the 'gateway' enum value. The agent would need to guess the purpose of companyId, profileId, and targetId, and the structure of the body is not clarified.
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 'Unbind' and the resource 'tool access profile' from a list of specific entities (company, agent, project, routine, or issue). It also provides the HTTP method and path, leaving no ambiguity about the tool's function. This distinguishes it from sibling tools like deleting a profile directly.
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. For example, it does not explain when to unbind a profile vs. deleting it, or when to use other binding/unbinding tools. The agent must infer usage purely from the action 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 minimal (readOnlyHint false, destructiveHint false, no idempotentHint). The description adds the HTTP method and authorization class, but does not disclose behavioral traits like side effects (e.g., whether ongoing operations are interrupted), state changes, or error conditions. With limited annotation coverage, the description should provide more 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 brief with two sentences, front-loading the purpose. However, the second sentence adds operational metadata that could be more concise or integrated better. No unnecessary words, but could be more informative in the same space.
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 complexity (nested objects, output schema exists), the description lacks completeness. It does not explain the return value, prerequisites (e.g., slot must exist and be local stdio MCP), or context around when a restart is appropriate vs a stop. Sibling tools with similar names add confusion without disambiguation.
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 50%, with only 'body' having a vague description. The description does not explain the role of 'path' parameters (companyId, id) beyond what the schema states. No additional meaning is provided to help the agent construct correct values.
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 title and description clearly state the tool restarts a local stdio MCP runtime slot. The sibling list includes similar tools (stop, restart for gateways), and the description distinguishes this as specifically for local stdio MCP slots, not gateway slots. The verb 'restart' is specific and the resource is well-defined.
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 'stop' or other 'restart' tools. There is no mention of prerequisites, conditions, or typical scenarios. The agent is left 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide basic behavior (write, not idempotent, not destructive). Description adds authorization class but no side effects or detailed behavioral traits beyond what annotations and schema imply.
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?
Description is short and front-loaded with purpose. Could add more context without being overly verbose, but it's efficient for its core message.
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 complexity of the input schema and lack of output schema details, the description is insufficient. Does not explain decomposition concept, accepted plan revision relationship, or return value expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet description provides no parameter-level explanations. Many nested fields are undocumented, leaving the agent without guidance on field 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?
Description clearly states it creates accepted plan decomposition child issues. Title matches. Sibling GET tool is for retrieval, so this distinguishes well.
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 on when to use this tool vs alternatives like pc_post_issues_by_id_children. Authorization class mentioned but no prerequisites or context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true. The description adds authorization context ('board_or_agent'), which is useful. However, it does not detail what 'force-release' entails (e.g., bypassing locks, consequences). 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two sentences), no fluff, and includes the REST endpoint and authorization. Could be slightly more structured but overall efficient.
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 destructive admin action, the description lacks details on preconditions, effects, and return values. Since an output schema exists, it doesn't need to explain return values, but it should still clarify the force-release semantics. Incomplete for such a sensitive 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 coverage is 50%, but the description adds no extra meaning for parameters. The 'body' parameter description is generic and the 'id' in path is not explained. The description should compensate for low schema coverage but fails to do so.
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 title and description clearly state the verb and resource: 'Force-release an issue (admin)'. It distinguishes itself from sibling issue operations like pc_post_issues_by_id_release by specifying 'admin' and 'force-release'.
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 on when to use this tool versus alternatives (e.g., pc_post_issues_by_id_release). The description only mentions authorization class but does not explain when force-release is appropriate versus other release operations.
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 non-read-only, non-idempotent operation. The description only adds the authorization class ('board_or_agent') but does not explain side effects (e.g., what happens after verdicts are submitted) or any constraints beyond the raw API info.
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 concise (3 sentences) and front-loaded with the purpose. However, it could benefit from brief parameter guidance.
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 a nested schema with enums and zero parameter descriptions, the description provides minimal context. It fails to cover what makes a valid verdict or the effect on the interaction.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description offers no explanation of parameters like 'verdicts' or its enum values (approve/reject/defer). It adds no semantic value over 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 ('Submit item verdicts') and the resource ('issue thread interaction'). It effectively distinguishes from sibling tools like accept/reject/respond by specifying 'verdicts'—a different operation.
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 provide explicit guidance on when to use this tool versus alternatives (e.g., pc_post_issues_by_id_interactions_by_interaction_id_accept). No when-to-use or when-not-to-use information is 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 provide readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds 'Authorization class: board,' which is a useful behavioral detail. However, it does not disclose other traits like side effects or response behavior. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two sentences—with no redundant information. It is front-loaded with the action statement. However, it could include more detail without becoming verbose.
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 (nested objects, two required parameters, many siblings), the description is too sparse. It omits explanation of the action's purpose, parameter usage, and return value, despite an output schema existing (not shown). Incomplete for effective agent use.
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 0% description coverage, meaning parameters are entirely undocumented. The description does not explain what pluginId, key, params, or companyId represent, leaving agents to guess. This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Invoke' and the resource 'plugin action' with the qualifier '(URL-keyed bridge)', which distinguishes it from sibling tools like pc_post_plugins_by_plugin_id_bridge_action. The title and first sentence are consistent and specific.
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 pc_post_plugins_by_plugin_id_bridge_action or pc_post_plugins_by_plugin_id_data_by_key. The description lacks context for selection among many plugin-related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it's not read-only and not destructive. The description adds 'Duplicate' which implies creating a copy, but it doesn't clarify side effects (e.g., whether assignments are copied, whether the original is unaffected). OpenWorldHint is true but not addressed.
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 very short (two sentences) and front-loaded. However, it includes unnecessary technical details like 'Paperclip operation' and 'Authorization class' which add noise without aiding an AI agent. Slightly wasteful but still 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 nested parameters, an output schema, and openWorldHint=true, the description is insufficient. It does not explain what the duplication entails, what the response contains, or any side effects. An agent would lack confidence in using it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description adds no meaning to parameters. For example, 'name' and 'includeAssignments' are not explained (e.g., whether name must be unique, what includeAssignments does). The schema provides structure but description should 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 title and description clearly state 'Duplicate a tool access profile', which is a specific verb-resource pair. Among sibling tools like patch/delete/get, duplication is a distinct operation, so it is well-differentiated.
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 creating a new profile from scratch or other profile-related tools. The description lacks usage context, such as prerequisites or post-conditions.
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 destructiveHint=true and idempotentHint=true. The description adds the HTTP method and authorization class but does not elaborate on side effects or cascading behavior beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short—two sentences—and front-loads the purpose. While concise, it sacrifices completeness; however, there is no wasted text.
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 it is a simple delete operation with annotations and an output schema, the description is minimally adequate. It omits crucial details like deletion permanence and impact on related data, but annotations partially compensate.
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 description does not explain any parameters. The body parameter has schema documentation, but the required companyId path parameter lacks description in both schema and text. The description fails to add meaning beyond the schema for the critical parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Delete a company' and provides the HTTP method and resource path. It clearly identifies the action and resource, and distinguishes itself from sibling tools like get or patch by nature.
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 on when to use this tool versus alternatives such as archiving or updating. The description mentions authorization class but does not provide context about prerequisites, reversibility, or consequences.
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 provide destructiveHint=true and idempotentHint=true, indicating this is a safe-to-repeat delete operation. The description adds that it is a DELETE, but lacks details on side effects (e.g., what if skill not starred) 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 concise, front-loading the main purpose. However, it could include brief parameter guidance without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description is partially complete. It lacks return value info (though output schema exists) and usage context, but the annotations partially compensate for behavioral aspects.
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 description does not describe the required parameters (companyId, skillId) beyond the name. With schema coverage at 50% and no parameter descriptions in the schema either, the agent lacks understanding of how to obtain these IDs.
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 'Unstar a company skill', which is specific and distinct from sibling tools like the starring counterpart. It also provides the HTTP method and authorization class.
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 on when to use this tool versus alternatives. It mentions authorization but does not explain prerequisites or context for unstarring, such as when a skill is already starred.
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 idempotentHint=true. Description adds HTTP method (DELETE) and authorization class (board_or_agent), but does not explain side effects like cascading deletions or irreversibility, which would be valuable for a destructive operation.
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?
Description is very short (3 lines) and to the point, with no fluff. However, the first line repeats the title, which is slightly redundant. Overall structure is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature and the existence of an output schema, the description does not mention return values (not required due to output schema) but also omits prerequisites (e.g., issue existence, permissions beyond auth class) and consequences. Adequate but not comprehensive.
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 50% (body has a description, path.id has none). The description provides no additional meaning for parameters; it merely states 'Delete an issue'. The underlying schema is minimal, and the description fails 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?
Description clearly states 'Delete an issue' with a specific verb and resource. Among many issue-related sibling tools (pc_get_issues_by_id, pc_patch_issues_by_id, etc.), this tool is uniquely identified as the delete 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 on when to use delete vs. alternatives like archiving (pc_post_issues_by_id_archive) or other state changes. The description lacks when-not-to-use information and does not mention 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 destructiveHint=true and readOnlyHint=false, so the description's 'Disable' aligns. It adds authorization class but does not elaborate on what disabling entails (e.g., permanence, effect on issue monitoring).
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?
Extremely concise: two lines with no superfluous information. The purpose is front-loaded and clear.
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 too sparse given the tool's complexity (2 parameters, output schema exists). Lacks return value info, usage flow, and behavioral details beyond the bare minimum.
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 description does not mention parameters. Schema coverage is 50% (body described, path.id not), but the description adds no meaning to either. Agent must infer parameter usage solely from 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 explicitly states 'Disable an issue watchdog', which is a clear verb-resource pair. It distinguishes from sibling tools like pc_put_issues_by_id_watchdog (enable/update) and pc_get_issues_by_id_watchdog (get).
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 on when to use this tool versus alternatives. It mentions authorization class but does not explain when to disable vs get or put watchdogs, nor prerequisites or limitations.
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 destructiveHint=true and idempotentHint=true. The description adds the HTTP method (DELETE) and authorization class, which confirms the destructive nature but does not explain side effects, reversibility, or impact on associated resources.
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 very brief at two sentences, repeating the title and providing the HTTP operation and auth class. It is efficient but could include more useful context without being 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?
For a destructive tool with an output schema and two parameters, the description omits important context such as when to revoke, prerequisites, or side effects. It is adequate but not fully complete given the complexity of the domain.
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 50%, with only the 'body' parameter described. The path parameters (connectionId, grantId) lack descriptions. The tool description does not clarify their meaning, format, or constraints, leaving the agent to infer from the endpoint pattern.
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 'Revoke a tool connection grant', using a specific verb and resource. It distinguishes from sibling tools like listing or adding grants by implying removal, and the title matches the description.
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. There is no mention of prerequisites, when revocation is appropriate, or comparison to other grant-related tools (e.g., GET grants, POST grants_installations).
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, idempotentHint, and destructiveHint, establishing the tool as safe and idempotent. The description adds the authorization class ('board_or_agent') and the HTTP method (GET), which provides minor additional context but does not elaborate on response behavior or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief with no wasted words. It front-loads the purpose and then provides the operation path and authorization. However, the structure is minimal and could be reorganized for clarity, e.g., by explaining the parameter expectation.
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 adequate for a simple read operation with an output schema present. It covers the basic purpose and authorization, but lacks explanation of what the UI parser script is used for or any prerequisites (e.g., valid adapter type). Given the tool's simplicity, the completeness is acceptable but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for the only parameter ('path' with nested 'type'). The description hints at the parameter by showing the endpoint path with '{type}', but does not explicitly document the parameter, its expected format, or constraints. The agent must infer the parameter meaning from the endpoint.
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 name and description clearly state that the tool retrieves the UI parser script for a specific adapter type. The endpoint path '/api/adapters/{type}/ui-parser.js' reinforces the resource being fetched. Among siblings like 'pc_get_adapters' and 'pc_get_adapters_by_type', this tool's unique purpose is evident.
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 the Paperclip operation and authorization class but offers no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, context, or exclusion criteria. The agent has to infer usage from the tool name and endpoint.
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 and destructiveHint=false. The description adds only the HTTP method (GET) and authorization class ('board'), which are minimal additions. It does not explain the meaning of 'company access' or what the response contains, leaving behavioral gaps beyond what annotations cover.
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 concise, consisting of two short sentences. The purpose is front-loaded, and the second sentence adds operational context (HTTP method and auth class). No redundant information is present.
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 annotations (readOnlyHint, idempotentHint, destructiveHint) and output schema, the description is adequate but not thorough. It lacks explanation of what 'company access' entails, the role of the admin authorization, and parameter details. For a simple read tool with good structured metadata, the description is minimally sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain the 'userId' parameter beyond its presence in the phrase 'user (admin)'. No format, constraints, or usage hints are given, leaving the agent to infer from the parameter name alone.
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 'Get company access for a user (admin)', using a specific verb ('get') and resource ('company access'). This distinguishes it from sibling tools like pc_get_admin_users (which retrieves users) and pc_put_admin_users_by_user_id_company_access (which modifies access).
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 when-to-use or when-not-to-use guidance is provided. The description implies this tool is for retrieving company access for a user, but does not mention alternatives or exclusions. The auth class 'board' suggests access control but does not clarify when to choose this over admin user 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 declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds the HTTP method (GET) and authorization class, but these do not significantly enhance behavioral understanding beyond the annotations. There is 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at two lines, but it repeats the title and includes technical details (Paperclip operation, authorization class) that may not be essential for an AI agent. Still, it is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description is not required to detail return values. However, it does not explain what the inbox contains or what 'lite' implies, leaving some ambiguity about the tool's scope. Given the tool's simplicity, this is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and the input schema coverage is 100%. The description does not need to add parameter details. Baseline for zero parameters 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 verb 'Get' and resource 'current agent inbox (lite)', which directly indicates the tool's function. However, it does not explain what 'lite' means or how it differs from the sibling tool 'pc_get_agents_me_inbox_mine', slightly reducing 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?
No guidance is provided on when to use this tool versus alternatives like 'pc_get_agents_me_inbox_mine'. The description mentions authorization class but does not help the agent decide which inbox variant to choose.
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 adds useful behavioral context beyond annotations: it specifies the HTTP method (GET) and authorization class ('board_or_agent'). This informs the agent about the access level and idempotent nature, complementing the readOnlyHint annotation 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at two lines, front-loading the purpose and providing critical operation details. It wastes no words, though it could be slightly more complete without adding verbosity.
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 simplicity of the tool (single parameter, output schema present, clear annotations), the description is minimally adequate. It conveys the basic action and access control, but lacks parameter documentation and usage context, leaving gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not mention any parameter. The only parameter (companyId) is not described, leaving the agent without guidance on how to obtain or format the ID. The description adds no value beyond what the schema 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?
The description clearly states 'Get a company', which is a specific verb+resource. It also provides the HTTP method and path, and is distinct from sibling tools like pc_get_companies (list). The title and description align perfectly.
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 does not provide any guidance on when to use this tool versus alternatives like pc_get_companies or when not to use it. There is no mention of preconditions 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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the HTTP method and authorization class ('board_or_agent'), which is useful but doesn't disclose other behavioral traits like caching behavior, rate limits, or that the output is a binary image. With annotations covering the basics, the additional value is moderate.
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 very concise at two lines. The first line repeats the title, which is somewhat redundant but acceptable. The second line provides technical details (endpoint, auth class). No filler, but the structure could be more integrated. Overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description doesn't need to detail return values. However, it fails to mention that the tool returns a PNG image (implied by title but not explicit). With one parameter and many siblings, more context (e.g., output is an image file, not URL) would improve completeness. Some gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. However, it merely restates the path ('companyId') without explaining what companyId is, its format, or its role. No parameter semantics are added beyond the schema structure.
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 explicitly states 'Get org chart as PNG', which is a specific verb-resource pair with format indication. The title reinforces this, and the endpoint path clarifies the resource. It is clearly distinguished from siblings like pc_get_companies_by_company_id_org (JSON) and pc_get_companies_by_company_id_org_svg (SVG).
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 over alternatives. It mentions authorization class but does not indicate when PNG format is preferred over SVG or JSON. No explicit comparison or usage context is 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, openWorldHint, idempotentHint, and destructiveHint, so the description adds minor value by stating the HTTP method and public authorization class. This is consistent with annotations but does not add significant behavioral context beyond what is already inferred.
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 very short (three lines) and front-loaded with key information. However, the title 'Health check' is repeated from the annotations, which is redundant. Overall, it is concise and structurally sound for a simple tool.
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 minimally complete for a zero-parameter health check with an output schema. However, it does not explain what the health check actually checks (e.g., system status, connectivity) or what kind of response to expect. The annotations provide safety hints, but the description lacks enough context for an agent to understand the tool's exact behavior.
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?
There are no parameters, and schema coverage is 100%. The description does not need to explain parameters. With zero parameters, a baseline of 4 is appropriate.
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 it is a health check, with the specific endpoint and authorization class. However, it does not differentiate from other health-related sibling tools like pc_get_plugins_by_plugin_id_health or pc_get_companies_by_company_id_tools_runtime_health, leaving ambiguity about the scope of this health check.
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 mentions 'Authorization class: public' which implies it is safe to call without authentication, but it provides no guidance on when to use this tool versus other health check tools (e.g., for plugins or companies). There is no explicit context about prerequisites, limitations, or 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?
The description adds the authorization class (board) and the exact API endpoint, providing some behavioral context beyond the annotations. However, it does not disclose further traits such as the content of the settings or any side effects. Annotations already indicate read-only and idempotent, so the added value is moderate.
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 concise, with the purpose stated in the first line. However, the second line adds technical details (HTTP method and auth class) that may be superfluous for an AI agent. It is not wasteful but could be more informative about the tool's context.
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 minimal and does not provide context about the scope of settings returned (e.g., all instance settings vs. subsets). Given the output schema exists and no parameters, the description could be considered adequate but lacks differentiation from similar siblings. It is not fully complete for an agent to understand the exact usage.
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 no parameters, and the input schema is empty. The description does not need to explain parameters. According to guidelines, baseline 4 for zero 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 verb 'Get' and resource 'instance settings'. However, it does not differentiate from sibling tools like pc_get_instance_settings_general or pc_get_instance_settings_experimental, which may cause confusion about which settings are returned.
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 guidelines are provided. The description lacks information on when to use this tool versus similar siblings like pc_get_instance_settings_general or pc_patch_instance_settings. It only includes technical details (HTTP method, auth class) that are not helpful for decision-making.
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 provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the authorization class 'public' and the API path, which are not in annotations. However, it does not discuss error cases, rate limits, or behavior for invalid tokens. The added value is modest.
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 concise: two sentences front-loading the purpose and adding the HTTP method and authorization. No superfluous text, though more details could be added 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?
For a simple retrieval tool with an output schema and rich annotations, the description is marginally adequate. It lacks context on when to use this vs. sibling tools and does not explain the parameters. However, the output schema covers return values, and annotations cover safety.
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 0% description coverage, so the description must clarify parameter meaning. It only hints via tool name that 'token' is the invite token and 'skillName' is the skill name, but does not explicitly define these. The description fails to compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a specific skill by name for a given invite. The verb 'Get' and resource 'skill by name for an invite' are specific and match the tool name. It distinguishes from siblings like pc_get_invites_by_token_skills_index (list all skills) and pc_get_skills_by_skill_name (global skill lookup).
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 does not explain prerequisites (e.g., need a valid invite token) or scenarios where this is preferred over listing all skills for an invite or fetching a skill globally.
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 provide readOnlyHint=true and destructiveHint=false, so the agent knows it is safe. The description adds the HTTP method and authorization class, but does not disclose additional behaviors like pagination, ordering, or response details. With annotations covering safety, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and to the point, with only two sentences. It is not verbose and front-loads the main 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?
The description is minimal but provides the essential information given that an output schema exists. It does not explain the concept of revisions or when to use this tool, but it is sufficient for a basic GET operation. However, the lack of parameter descriptions reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description should compensate. It mentions the URL pattern (issue id and document key) but does not explicitly describe what each parameter means. The agent may infer that 'id' is the issue ID and 'key' is the document key, but it is not explicit.
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 title and description clearly state the tool lists revisions of a specific issue document. The purpose is specific and distinguishes from siblings like pc_get_issues_by_id_documents (lists documents) and the create revision sibling.
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 on when to use this tool vs alternatives. For example, when to list revisions vs when to get a single revision (if such tool exists) or when to create a revision. The description only states the HTTP method and auth class.
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 API path and authorization class, but no additional behavioral details like response format or potential errors.
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 sentences with no filler. However, the second sentence is more of a technical reference than explanatory. Efficient but could be slightly more informative without adding 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?
The description tells the resource and auth class, but does not summarize the health response structure. An output schema exists but the description does not leverage it to provide a high-level understanding. Adequate for a simple health check but leaves details to 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?
Schema coverage is 0%: no descriptions on parameters. The description does not explain the meaning or source of 'pluginId', leaving the agent to infer from the name alone.
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 'Get plugin health' which is a specific verb+resource, clearly distinguishing it from sibling tools like pc_get_plugins_by_plugin_id (which retrieves plugin details, not health).
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 on when to use this tool versus alternatives. It does not mention situations to use or avoid, nor does it reference sibling tools for comparison.
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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's a safe read operation. The description adds the authorization class ('board_or_agent') and the HTTP path, which is useful context but does not detail response format, caching, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with two sentences, no redundancy, and front-loads the primary purpose. However, the first sentence merely repeats the title, adding no new information.
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 nature of file serving and the presence of a good annotation set, the description is mostly adequate. However, it lacks details about response content (e.g., MIME type, binary data) and error handling (e.g., 404 if file not found).
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 coverage is 0%, meaning the description provides no additional explanation for the parameters. Although parameter names (pluginId, filePath) are self-explanatory, the description misses opportunities to clarify expected formats, path conventions, or constraints, which would be valuable given the nested structure.
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 serves a static file for a plugin's UI, using a specific HTTP GET operation and path template. The title and name are consistent and distinguish this from sibling tools like pc_get_plugins_by_plugin_id (which retrieves plugin metadata) or other plugin operations.
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 pc_get_plugins_by_plugin_id or pc_get_plugins_ui_contributions. There is no mention of prerequisites, context, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, non-destructive. Description adds minimal behavioral context like 'Authorization class: board_or_agent'. 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?
Extremely concise with two sentences. No unnecessary information; every part adds 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?
Given presence of output schema and annotations, description is minimally adequate. However, lack of parameter explanation and limited use-case context makes it incomplete for an agent to use confidently.
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 has one optional parameter (companyId) with 0% description coverage. Description does not explain its purpose, leaving the agent without necessary context.
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?
Title and description both state 'List gateway runtime slots' clearly. However, it does not distinguish from sibling tools like pc_get_companies_by_company_id_tools_runtime_slots.
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?
Description provides the HTTP method, path, and authorization class, which offers usage context. But no guidance on when to use this tool vs 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 already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds the endpoint and authorization class but does not disclose any behavioral traits beyond what annotations already convey.
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 succinct sentences: one for purpose and one for endpoint details. No wasted text; front-loaded with the core action.
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, presence of output schema, and annotations covering safety, the description is adequate. It could mention the return type (list of tools) but the output schema likely covers that, so this is nearly 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?
No parameters exist, and schema coverage is 100%. According to guidelines, a baseline of 4 is appropriate when there are 0 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?
Description clearly states the action: 'List tools available to a gateway session'. It includes the HTTP method and path for further clarity. However, it does not explicitly differentiate from sibling tools like pc_get_tool_gateway_runtime_slots, which also lists resources, but the purpose is distinct enough.
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 on when to use this tool versus alternatives. The description only states what it does without providing context for when it is appropriate or when to choose a different tool.
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 readOnly, idempotent, non-destructive. Description adds HTTP method and auth class, but does not contradict annotations and adds minimal extra 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?
Description is concise (two sentences), but the second sentence is technical and may not add value for an AI agent.
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 a simple list tool with one parameter and an output schema, the description is minimally adequate but lacks detail on output or filtering 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?
Schema coverage is 0%, and the description does not explain the 'path' object or 'profileId' parameter. No additional 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 clearly states the action ('List') and the resource ('new catalog tools pending profile review'), 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?
No guidance is provided on when to use this tool versus siblings; no mention of 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?
Annotations already indicate non-read-only, idempotent, and non-destructive behavior. The description adds the authorization class ('board') as additional context but does not disclose what happens during the callback (e.g., token storage). 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, consisting of two lines. It is front-loaded with the purpose and provides essential operation details. However, it could be slightly expanded to add behavioral context without losing 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 covers the basic purpose and operation but lacks context about the OAuth flow (e.g., that this is a callback endpoint invoked by the browser after user authorization). With no parameters and an output schema, more context would help the agent understand the tool's role.
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?
There are no parameters in the input schema, so the description does not need to add parameter details. The baseline of 4 is appropriate as there is no missing parameter information.
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 it handles a tool app OAuth callback, which is a specific verb and resource. It distinguishes from sibling tools like pc_post_tools_oauth_by_connection_id_start that initiate the OAuth flow.
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 includes the HTTP method and authorization class but provides no guidance on when to use this tool versus alternatives, such as the start tool. The OAuth flow context is not explained.
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 says 'stream' which implies a streaming response, but no details about streaming behavior (e.g., how to handle chunks, termination). Annotations provide readOnlyHint=false and destructiveHint=false, but the description adds minimal behavioral context beyond the streaming aspect.
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 short (two sentences) and front-loaded with the title and requirement, but the lack of parameter documentation and streaming details makes it less valuable than it could be. It is concise but incomplete.
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 that the tool has a complex streaming behavior, nested parameters, and an output schema, the description lacks critical context: no explanation of the streaming format, error handling, or parameter roles. It only covers the prerequisite and auth class.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter 'body' with nested required fields, but schema description coverage is 0%. The description does not explain the meaning or purpose of any parameter (e.g., companyId, message, taskId), forcing the agent to infer from names alone.
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 title and description clearly state the tool streams a board-level chat response, with a specific prerequisite. It stands out from the many sibling tools due to its specific domain.
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 specifies the requirement 'requires enableConferenceRoomChat' which is a clear usage guideline. However, it does not explicitly indicate when to use this tool versus alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true. The description adds authorization class (board_or_agent) which is useful, but does not explain the implications of archiving (e.g., reversibility, visibility changes). Minimal value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: two sentences, front-loaded with purpose and endpoint info. 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 tool has an output schema (not shown), so return values need not be explained. However, the description lacks detail about the effect of archiving (e.g., does it disable the company? Is it reversible?). Adequate but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (body described, path not). The description does not add meaning beyond what the schema provides for the required companyId parameter. Baseline 3 due to partial coverage and no enrichment.
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 title and description clearly state 'Archive a company', which is a specific verb+resource. However, no differentiation from sibling tools like delete or patch is provided, but the name itself distinguishes it as an archive 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 on when to use this tool versus alternatives such as pc_delete_companies_by_company_id. The description lacks context about prerequisites or exclusions, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-destructive write (readOnlyHint=false, destructiveHint=false). The description adds the HTTP method (POST) and authorization class (board_or_agent), which provides transparency about how the operation is performed. No contradictions with annotations. The behavioral trait of 'moving' is disclosed, but no further details about side effects (e.g., metadata preservation) are given.
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, consisting of two short sentences that front-load the purpose. No extraneous information. It efficiently communicates the core action and necessary operation details.
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 important context: the types of items that can be moved (routine, skill), the effect of providing null folderId (removing from folder), and the tool's output (though an output schema exists). Given the complexity of the input schema (nested object with optional fields), the description is insufficient for an agent to correctly select and invoke this tool without relying solely on schema inspection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters, but it does not. It fails to mention that 'kind' accepts routine/skill, that 'itemId' is a UUID, or that 'folderId' is optional (null means remove from folder). The agent must infer all meaning from the schema structure and property names, leaving a significant semantic gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool moves an item into or out of a folder, specifying the verb (move) and resource (item/folder). It distinguishes from sibling folder operations like creating, updating, or deleting folders, as well as moving folders themselves (e.g., pc_post_companies_by_company_id_folders_by_folder_id_move).
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. There is no mention of when to move an item vs. when to use other folder operations, or what prerequisites (e.g., target folder existence) are needed. The context of the move (into/out of a folder) is implied but not explicitly contrasted with sibling 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 indicate it's not read-only, idempotent, or destructive. The description adds the HTTP method and authorization class, which provides some behavioral context beyond annotations. However, it does not disclose side effects or other behaviors.
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 lines) and front-loads the primary action. While concise, it lacks depth; a bit more detail would improve usability without sacrificing 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?
The tool is a creation operation with required parameters, but the description does not explain what a skill test-run template is, what the body should contain, or what the output schema describes. This leaves the agent under-informed for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameters. The schema defines required fields (name, body) and optional description, but their semantics are left to inference, which is insufficient for correct invocation.
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 title and description clearly state 'Create a skill test-run template' with the specific HTTP method and path. This distinguishes it from siblings like get, patch, and delete operations for the same 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?
Provides the authorization class ('board_or_agent') which is a prerequisite. However, no explicit guidance on when to use this tool versus alternatives like list or update. The HTTP method implies creation, but the description could be clearer about 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 indicate destructiveHint=true, so the description's mention of 'board_or_agent' authorization adds some context. However, the description does not disclose side effects (e.g., invite becomes invalid, notifications sent) or other behavioral traits beyond what annotations provide. The description 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 very concise, consisting of three short sentences. It is front-loaded with the purpose. However, it lacks any structural elements like bullet points or sections, though the brevity itself is not penalized. 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 simple destructive action with an output schema, the description is adequate but not complete. It omits context about prerequisites (e.g., invite must exist), the effect of revocation (e.g., invite code invalidated), and the return value. The output schema exists but its contents are not summarized.
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 50% (only the body parameter has a description). The tool description adds no additional meaning to the parameters; it does not explain how to obtain the inviteId or what the optional body payload is for. The schema's body description is already present, so the description adds no value beyond structured data.
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 title and first sentence clearly state 'Revoke an invite', which is a specific verb ('Revoke') and resource ('invite'). This distinguishes it from siblings like pc_post_invites_by_token_accept (accept invite) and pc_get_companies_by_company_id_invites (list invites).
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 vs alternatives. It does not mention prerequisite conditions, such as the invite needing to be in a pending state, nor does it clarify that revoking is only applicable to existing invites. No explicit when-not-to-use or alternative references.
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 readOnlyHint=false and destructiveHint=false, so the description adds minor context via the authorization class. However, it discloses no behavioral traits beyond the operation's HTTP method and path. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with two lines: the first states the purpose, the second provides technical details (HTTP method, path, auth). No extraneous words, but it might be too minimal for full clarity.
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 simplicity (2 params, one required approvalId, output schema present), the description covers the basic purpose and authorization. However, it lacks explanation of what 'linking' entails, any side effects, or return value (though output schema may help). Adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for parameters, and the description does not explain what 'id' (path) or 'approvalId' (body) represent. The description adds no meaning beyond the schema structure, failing to compensate for the lack of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Link' and the resource 'approval to an issue', making the action unambiguous. It distinguishes from sibling tools like pc_get_issues_by_id_approvals and pc_delete_issues_by_id_approvals_by_approval_id, which handle listing and removal.
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 mentions authorization class ('board_or_agent') but provides no explicit guidance on when to use this tool versus alternatives. The purpose is implied by context (siblings for listing/deleting), but no when/not-to-use instructions 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 readOnlyHint=false (mutation) and destructiveHint=false. The description adds the HTTP operation and auth class, but does not explain side effects (e.g., whether it creates a run, what the immediate response is). This is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose. The second sentence provides implementation details (HTTP operation, auth class) that some agents might find useful, though it is not essential. Overall, it is well-structured and brief.
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 simplicity of the tool (triggering a monitor check) and the presence of an output schema (not shown), the description is minimal but functional. It lacks context about what a monitor check is or what the outcome will be, which could be helpful for an AI agent deciding to use this tool.
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 description does not explain the 'id' parameter (issue ID) or the optional 'body' parameter. Schema coverage is 50%, but the description adds no value beyond the schema. The agent would benefit from knowing what 'id' refers to and when 'body' is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (run a monitor check) and the resource (an issue). It also includes the HTTP method and authorization class, which adds specificity. No sibling tool has a similar name, so it is well-distinguished.
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 does not provide any guidance on when to use this tool vs alternatives, nor does it mention prerequisites (e.g., having a monitor configured). The context for triggering a manual check is only implied by 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 already indicate mutation (readOnlyHint false). The description adds the HTTP method (POST) and authorization class ('board'). However, it does not describe side effects, whether triggering is asynchronous, or the return value (output schema exists but not documented).
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 sentences with zero fluff. Every word serves a purpose, stating the action, HTTP method, endpoint, and auth class.
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 nested objects and an output schema, the description omits critical details: what triggering accomplishes, expected outcome, error conditions, or return value. The agent cannot fully understand the tool's behavior from the description alone.
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 50% (only 'body' has a description). The description does not elaborate on parameters; it only shows the URL template with path parameters, which is already evident from the schema structure. No additional meaning for 'pluginId' or 'jobId' provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool triggers a plugin job, distinguishing it from sibling tools like pc_get_plugins_by_plugin_id_jobs (list jobs) and pc_get_plugins_by_plugin_id_jobs_by_job_id_runs (get runs). The verb 'trigger' and resource 'plugin job' are specific.
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 on when to use this tool versus alternatives, no exclusions, and no context about prerequisites (e.g., job must exist). The description assumes the agent knows when triggering is appropriate.
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 adds the authorization class ('board') and the exact endpoint, which are not in annotations. However, it does not describe side effects (e.g., whether the refresh is synchronous or what happens to the existing catalog).
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 very concise (two sentences) and front-loaded with the title. It includes relevant technical details without unnecessary 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 adequate for a simple POST operation, but it lacks context about the refresh process (e.g., triggers, effects). Given the complexity and available siblings, more context would be helpful.
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 50%, and the description does not elaborate on the 'connectionId' parameter or the optional body. It adds no meaning beyond the input schema's minimal 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 'Refresh a tool connection catalog' with a specific verb and resource. It also provides the exact HTTP method and path, distinguishing it from the GET catalog sibling.
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 on when to use this tool versus alternatives (e.g., fetching the catalog first). The description does not mention preconditions or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds the specific HTTP method (DELETE) and authorization class ('board_or_agent'), which provides useful behavioral context beyond the annotations. There is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and to the point, consisting of two sentences. It is concise without being overly terse. However, it could be slightly more structured (e.g., bullet points) to improve readability, but the current form is acceptable.
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 that the tool is a delete operation with nested parameters and an output schema, the description is minimal. It does not explain what happens on success/failure, any side effects, or the structure of the response. While the output schema exists, the description should still provide some context about the operation's behavior. The missing parameter descriptions further reduce completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 50% description coverage: the body parameter has a description, but the required path parameters (id, commentId) lack any description. The overall description does not elaborate on these path parameters, leaving their meaning ambiguous. The description should compensate for the missing schema descriptions but does not.
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 explicitly states 'Delete an issue comment', which is a clear verb+resource. It also includes the HTTP method and endpoint, further reinforcing the purpose. This clearly distinguishes it from sibling tools like pc_get_issues_by_id_comments or pc_post_issues_by_id_comments.
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 prerequisites, context, or scenarios where this tool is appropriate. The agent must rely solely on the tool name to infer 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?
The description includes the HTTP method and path, and the authorization class, adding some behavioral context beyond the annotations (which already declare readOnlyHint and destructiveHint). However, it does not disclose other important traits like rate limits, pagination, or whether the list includes all users across all companies.
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, consisting of two sentences that front-load the main action. It includes useful details (HTTP method, path, authorization class) without any waste. Every sentence 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?
The tool is simple with no parameters and an output schema exists, so the description covers the essential purpose. The inclusion of the HTTP path and authorization class adds useful context. However, it lacks any guidance on scope (e.g., does it list users from all companies?) or limitations, which would be helpful for 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?
There are no parameters, and schema coverage is 100%. The description adds no parameter semantics because none are needed. Baseline score of 3 is appropriate.
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?
Clearly states 'List all users (admin)' which identifies the verb and resource. Includes the HTTP method and path, and the authorization class. However, the description does not explicitly differentiate from sibling tools like pc_get_companies or pc_get_admin_users_by_user_id_company_access.
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 pc_get_companies for listing companies or pc_get_admin_users_by_user_id_company_access for a specific user's company access. The context of 'admin' and 'board' authorization is implicit but not enough for clear decision-making.
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 readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds the HTTP method and authorization class, providing modest additional context without contradicting 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 concise with two sentences, front-loading the purpose. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with one parameter, the description provides the HTTP method and auth class, but lacks explanation of the 'id' parameter. The presence of an output schema mitigates the need for return value descriptions, but parameter context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate but does not explain the 'id' parameter (presumably the agent ID). No parameter semantics are added beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'agent API keys'. It distinguishes from sibling tools like pc_post_agents_by_id_keys (create) and pc_delete_agents_by_id_keys_by_key_id (delete).
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 (e.g., create or delete key tools). It only describes the operation itself.
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, destructiveHint=false. The description adds the authorization class and endpoint, which provide minor additional context but do not reveal further behavioral traits (e.g., impact, data returned). 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) but the first sentence is redundant with the title. However, it is concise and front-loads the purpose. Could be slightly improved by removing the tautology.
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 (no parameters, read-only, output schema available), the description provides the endpoint and authorization class, which is sufficient for an AI agent to understand its function. Could mention that it returns the authenticated agent's details, but output schema covers that.
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?
There are zero parameters, so schema coverage is 100%. Per rubric, baseline is 4. No parameter description needed, and none 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 name and title clearly indicate retrieval of the current agent. The description restates the purpose and adds the API endpoint, but lacks explicit differentiation from sibling tools like pc_get_agents_by_id. Still, the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides the API endpoint and authorization class but offers no guidance on when to use this tool versus alternatives (e.g., pc_get_agents_by_id for other agents). No when-not or context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the HTTP method (GET) and authorization class ('board_or_agent'), adding some behavior beyond the annotations which already mark it as read-only, non-destructive, and idempotent. However, it does not detail pagination, sorting, or other behavioral traits.
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, consisting of two short sentences with no unnecessary words. It front-loads the core purpose and provides supplementary details efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with one parameter and a read-only annotation, the description is adequate but lacks detail on the output format and the specific meaning of the 'id' parameter. Since an output schema exists, return values need not be explained, but the parameter description gap remains.
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 0% description coverage and the description does not explain the 'id' parameter. While the parameter name 'id' suggests an approval ID, the description should explicitly clarify this to ensure correct 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 'List approval comments' uses a specific verb and resource, clearly distinguishing it from sibling tools like 'pc_get_issues_by_id_comments' which lists issue comments. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as when to prefer it over 'pc_get_issues_by_id_comments' or 'pc_post_approvals_by_id_comments'. No explicit context or exclusions 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 and destructiveHint=false, establishing it as a safe read. The description adds that it is a GET operation with authorization class 'board_or_agent,' providing modest behavioral context beyond annotations. No mention of latency, data freshness, or pagination, but the safety profile is well-covered.
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 short sentences conveying the operation, endpoint, and authorization. Every sentence adds value without redundancy or excess. Ideal for an AI agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown in input schema), the description need not document return values. It covers the essential behavioral traits (read-only, auth class) but lacks context on what a 'budget overview' entails (e.g., spending totals, budget status). Still, it is adequate for a simple read operation with good annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter `companyId` is self-explanatory as a path identifier. Although the description has 0% schema coverage (no explicit parameter descriptions), the endpoint path in the description (`/api/companies/{companyId}/budgets/overview`) implicitly documents the parameter. Additional details on data type or format are unnecessary given the parameter's simplicity.
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 title and description clearly state 'Get budget overview,' indicating a read operation on a high-level budget summary. It is distinct from sibling tools like `pc_patch_companies_by_company_id_budgets` (update) or `pc_post_companies_by_company_id_budgets_policies` (create policy), but the description does not elaborate on what the overview contains, which would elevate 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 alternative budget tools (e.g., for detailed budget editing or policy management). It only states the HTTP method and auth class, leaving the agent to infer usage context from the tool 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 description adds the exact API path (GET /api/companies/{companyId}/execution-workspaces) and authorization class ('board_or_agent'), which are beyond the annotations. However, it does not describe return format, pagination, or other behavioral aspects. Since annotations already declare readOnlyHint and destructiveHint, the description provides moderate added value.
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 three sentences: one for purpose, one for API details, and one for authorization. It is front-loaded and concise, with no unnecessary words. It earns a 4 because it is efficient, though slightly more structure could improve readability.
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 one parameter and an output schema, the description provides the purpose, API path, and authorization context. It lacks mention of filtering or pagination, but the output schema likely covers that. Given the tool's simplicity and the annotations, the description is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning the description does not explain any parameters. The only parameter is 'companyId' (string, required), which is self-explanatory, but the description fails to add any additional meaning or context about the parameter. Per guidelines, low coverage requires compensation, which is absent.
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 title and description clearly state 'List execution workspaces for a company', using a specific verb and resource. Among many sibling tools, this one is distinct as it lists execution workspaces for a given company, with no 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 does not provide any guidance on when to use this tool versus alternatives. It only states what it does, without exclusions or context for when not to use it. No sibling differentiation is mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds the HTTP method (GET) and authorization class ('board'), providing useful behavioral context 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 description is short and front-loaded with the purpose. Every sentence contributes value, but it could be more structured (e.g., adding a sentence about usage context without becoming verbose). Score 4 because it is efficient but minimal.
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 that there is an output schema, the description does not mention what the tool returns (e.g., list of action requests, pagination details). It lacks completeness for a tool with parameters and output, leaving the agent without full 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?
The description has 0% schema coverage, meaning it explains none of the parameters. The only parameter (companyId inside path) is not described, leaving the agent to infer from its name alone. This is insufficient for a required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List pending tool action requests', which is a specific verb ('List') and resource ('pending tool action requests'). It clearly distinguishes from sibling tools that create or manage action requests (e.g., pc_post_companies_by_company_id_tools_action_requests_aa728686a4).
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 specify prerequisites, context, or when not to use it, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds the specific HTTP method and path (GET /api/companies/{companyId}/tools/profiles) and authorization class ('board'), which are helpful operational details beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences), but the first sentence repeats the title. The second provides useful technical details. It is concise but could be restructured to avoid redundancy and include more context.
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 that an output schema exists, the description does not need to explain return values. However, it does not elaborate on what 'tool access profiles with entries and bindings' entails or how the results are structured. The tool is simple but lacks explanatory depth.
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?
There is only one parameter (companyId), and the description does not explain its role or format. Schema coverage is 0%, so the description should compensate but does not. The parameter is straightforward but no guidance is offered.
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 tool access profiles with entries and bindings, and the title reinforces this. It is distinct from sibling tools like pc_get_companies_by_company_id_tools_policies or pc_get_companies_by_company_id_tools_trust_rules, 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 pc_get_companies_by_company_id_tools_profiles_effective or other profile-related tools. No prerequisites or exclusions are given.
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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds the HTTP method (GET) and authorization class ('board'), which are beneficial for understanding access requirements and safety 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 consists of two short, clear sentences with no wasted words. It is appropriately sized and directly states the operation and additional technical details about the endpoint and authorization.
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 tool is simple with few parameters and annotations covering safety, the description lacks explanation of what 'tool trust rules' are, what the response contains, and any potential pagination or filtering. Given the output schema exists, some context is missing for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not describe the single parameter 'path.companyId' at all (0% schema description coverage). The input schema shows it is a required string but provides no further context. The description fails to add any 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 states 'List tool trust rules', which clearly specifies the verb (list) and resource (tool trust rules). The tool name is long but the description succinctly identifies its purpose, and it distinguishes from sibling tools like the creation endpoint for trust rules.
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 posting trust rules or other list operations. There is no mention of prerequisites, context, or typical use cases.
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 adds that it is a GET operation with an 'Authorization class: board', which provides some behavioral context beyond the annotations (readOnlyHint, idempotentHint). However, the annotations already cover the safety profile adequately.
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 sentences that convey the essential information (purpose and endpoint). No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, strong annotations, and an output schema (not shown but indicated), the description is mostly complete. It could benefit from clarifying the nature of the stats (e.g., aggregate counts, performance metrics) but is sufficient for a simple read-only 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 tool has no parameters, and the schema coverage is 100%, so the description does not need to add parameter details. It adds no extra meaning, but the baseline is 3 for a parameterless tool.
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 retrieves 'Company stats' and specifies the HTTP method (GET) and endpoint. However, it does not elaborate on what specific statistics are returned, which could be ambiguous, but the verb and resource are 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?
No guidance is provided on when to use this tool versus alternative tools like pc_get_companies (which likely lists companies) or other stats tools. There is no mention of prerequisites or context where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint. The description adds the HTTP method (GET) and authorization class, which provides some extra context. However, it does not disclose potential errors (e.g., 404), rate limits, or other behavioral nuances. The description adds marginal value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very brief—two sentences—and front-loaded with the core purpose. No unnecessary words or information. 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?
Given the simplicity (one parameter, output schema exists, annotations present), the description is adequate but minimal. It does not include examples, common errors, or return value hints (though output schema covers returns). Could be more helpful with usage guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the input schema provides no descriptions for the path.id parameter. The description does not clarify what the ID represents (e.g., goal ID, format, or constraints). It adds no meaning beyond the schema structure.
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 title and description both state 'Get a goal,' clearly indicating the action and resource. The HTTP method and path further specify the operation. It distinguishes from sibling tools like pc_patch_goals_by_id (update) and pc_get_companies_by_company_id_goals (list).
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 the HTTP method and authorization class, which implies usage context (retrieve a single goal by ID). However, it does not explicitly state when to use this tool versus alternatives or provide 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 mark the tool as read-only, idempotent, and non-destructive. The description adds the HTTP method and authorization class, but does not disclose other behaviors like rate limits, response size, or that the document is generated (not cached). The annotation openWorldHint is not addressed.
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 very short with no wasted words. However, the first sentence is redundant with the title, slightly reducing efficiency. Still, it is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/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 is minimally adequate. It states the HTTP operation and auth class but does not describe what the OpenAPI document contains or how to interpret the response. Given the simplicity, it meets the minimum but could be more 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?
The input schema has no parameters, so the description cannot add parameter meaning. Schema coverage is 100%, baseline is 3. The description mentions the endpoint and auth class but these are not parameter-related.
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 title and description clearly state the tool retrieves the generated OpenAPI document. The description adds the specific endpoint (GET /api/openapi.json) and authorization class (public), which uniquely identifies its purpose 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 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 pc_get_health or pc_get_companies. The usage context is implied but there are no explicit conditions, exclusions, or mentions of 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds the specific HTTP method (GET) and authorization class, which is useful. However, it does not describe the output format, pagination, or any side effects beyond what annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: one stating the purpose, one providing technical details. No wasted words. Front-loaded. Appropriate for a simple list operation.
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 no parameters, annotations cover safety, and there is an output schema (not shown but present), the description is minimally adequate. However, it does not explain what 'plugin tools' are or how they relate to other resources, which could reduce completeness 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 with 100% schema description coverage. The description does not need to add parameter information. The baseline score of 4 is appropriate as there is no gap.
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 verb 'List' and resource 'plugin tools'. The title reinforces this. However, it does not explicitly differentiate from sibling tools like pc_get_plugins or pc_get_plugins_examples, leaving ambiguity about what 'plugin tools' specifically refers to.
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 on when to use this tool versus alternatives. The description only provides technical details (API endpoint and auth class) but lacks context about use cases, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as readOnlyHint, idempotentHint, and not destructive. The description adds that it requires 'board_or_agent' authorization, which is useful context about permissions not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (3 lines) and lacks detail beyond the endpoint and authorization class. While concise, it sacrifices useful information, making it minimally adequate.
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 simplicity and the existence of an output schema, the description could suffice with minimal information. However, the lack of parameter explanation and usage guidance makes it barely complete for an agent to use confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should explain parameters. However, it only mentions the endpoint path and does not describe the 'id' parameter, leaving the agent to infer its meaning from the tool name and context.
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 title 'Get a project' and description 'Get a project' combined with the HTTP path clearly indicate this tool retrieves a single project by ID. It is distinct from sibling tools like pc_get_companies_by_company_id_projects which lists projects, and pc_patch_projects_by_id which updates a project.
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 explain that this is for fetching a specific project when the ID is known, nor does it contrast with listing or updating operations.
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, idempotentHint, destructiveHint. The description adds the HTTP method and authorization class, which provides additional context beyond annotations. However, it does not disclose what the response contains or any edge cases.
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 very short (two sentences) with no unnecessary information. However, the second sentence (implementation detail) could be omitted for agent consumption, but it does not detract significantly.
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 and annotations providing safety hints, the description sufficiently states the tool's purpose. The output schema would cover return details, so the description is appropriately complete for a simple read operation.
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?
No parameters exist, and schema coverage is 100%. The description need not add parameter details, so it adequately fulfills this dimension.
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?
Description clearly states 'Get current user sidebar preferences', which specifies the verb and resource. However, it does not differentiate from sibling tools like pc_get_companies_by_company_id_sidebar_preferences_me, which also accesses sidebar preferences but at a different scope.
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 on when to use this tool versus alternatives (e.g., the company-scoped version or the put tool). The description lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the HTTP endpoint and authorization class ('board_or_agent'), which provides some context but does not disclose additional behavioral traits (e.g., pagination, response format). 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 extremely concise—two short sentences that front-load the main purpose. Every sentence is functional; no redundancy or unnecessary 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?
Given the annotations provide safety info and the tool has an output schema (not shown), the description is minimally complete. However, it omits any hint about what the response contains (e.g., skill properties). For a simple fetch tool, this is adequate but could be improved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not elaborate on the 'skillName' parameter (e.g., case sensitivity, allowed characters, or existence expectations). The single parameter is self-explanatory given the tool name, but no added value beyond the schema structure.
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 'Get a skill by name', which is a specific verb+resource. It distinguishes from sibling skills tools like pc_get_skills_catalog or pc_get_skills_available by focusing on retrieval by name. The HTTP method and path further solidify purpose.
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 pc_get_skills_index or pc_get_skills_catalog. While it mentions authorization class, it does not explain usage 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint false. The description adds the authorization class and HTTP method, providing extra behavioral context without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at two sentences. The first sentence repeats the title, which is slightly redundant, but overall it is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and presence of an output schema, the description is minimally adequate. However, it lacks context about what 'catalog teams' are and typical use cases, leaving some ambiguity.
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 is empty, so no parameters require explanation. Schema coverage is 100% by default. The description does not need to add parameter info, achieving the baseline of 3.
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 'List catalog teams', which clearly indicates the verb and resource. However, it does not differentiate from sibling tools like pc_get_skills_catalog or pc_get_teams_catalog_by_catalog_id, lacking specificity about what 'catalog teams' are.
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 on when to use this tool vs alternatives. The description mentions the HTTP operation and authorization class but does not explain the context or exclusions, such as when to list all teams vs retrieving a specific one.
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. The description adds context by specifying the endpoint path and 'Authorization class: public', which informs about accessibility. This is useful 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 extremely concise (3 lines) with no redundant information. Every sentence serves a purpose: purpose statement, HTTP operation, and authorization class.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with output schema, the description is adequate but missing parameter explanation. It would benefit from clarifying what 'named MCP gateway endpoint' means or what the response contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the tool description provides no explanation of the parameter 'gatewayId'. Without context, an agent cannot know what value to provide.
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 'Describe a named MCP gateway endpoint', which clearly indicates a read operation to retrieve details of a specific MCP gateway. This distinguishes it from sibling tools like the POST variant or other gateway-related 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. It mentions the HTTP method and authorization class but does not specify 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only and non-destructive behavior. The description adds the HTTP method (PATCH), exact endpoint, and authorization class ('board_or_agent'), providing useful behavioral context 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 description is concise with two lines: a clear title and a technical detail line. It front-loads the purpose. However, 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.
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 (not shown) and sibling tools for context, the description omits critical update details: what fields are updatable, whether it's a partial update, and any response structure. For a mutation tool, this is insufficient.
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 coverage is 50%, but the description adds no explanation of path parameters (companyId, skillId, commentId) beyond their names. The body parameter is described as 'Optional JSON compatibility payload. The source OpenAPI operation does not declare a request schema,' which is vague and adds little meaning.
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 'Update a skill comment', using a specific verb and resource. Among sibling tools, there are separate tools for getting, posting, and deleting comments, making the purpose distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 POST (create) or DELETE (remove). It does not specify prerequisites or context for updating.
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 adds the HTTP method, endpoint path, and authorization class ('board_or_agent'), which supplements the annotations. However, it does not describe side effects, required user interaction, or what happens upon successful trigger. Annotations already indicate it is a mutation (readOnlyHint false) and not destructive, so the description provides some useful context but not comprehensive behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two sentences that front-load the core purpose. Every word is necessary and no fluff is present.
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 2 parameters, nested objects, and an output schema, the description is minimal. It explains the basic action and endpoint but omits context such as when Claude login is needed, what triggers the process, or the structure of the response. The output schema exists but the description does not reference it, leaving the agent to infer return behavior from other sources.
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 description does not elaborate on the parameters beyond what is in the input schema. The schema covers the parameters, but the description adds no extra semantic meaning, such as the role of the 'body' parameter or the expected format of 'id'. With 50% schema coverage, the description should compensate but fails to do so.
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 ('Trigger Claude login') and the target resource ('for agent'). The verb 'Trigger' is specific and the resource is unambiguous. Although there are many sibling tools, this tool's purpose is distinct and directly conveyed.
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 other agent authentication tools. There is no mention of prerequisites, typical scenarios, or conditions under which the tool should or should not 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 non-read-only (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds that it is a POST operation and requires 'board' authorization, which provides some context. However, it does not elaborate on what a 'managed restart' entails or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) and front-loads the purpose. The second sentence contains technical details but is not overly long.
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, so return values are covered. The description mentions 'managed' but does not explain what that means or any prerequisites. With one optional parameter, the information is adequate but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (one parameter 'body' with a clear description). The description does not add parameter details, but the schema already fully documents 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 clearly states the action ('Request') and the resource ('a managed dev-server restart'). The verb and noun are specific and distinct from sibling tools, which are all different operations.
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 or when to avoid it. No alternatives are mentioned, and no context is provided for appropriate invocation.
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 adds the authorization class ('Board') which is beyond annotations. However, it does not disclose other behavioral traits such as idempotency, side effects (e.g., overwriting previous default), or error conditions (e.g., if the config ID does not exist). Annotations already indicate it is a write operation (readOnlyHint=false) and not destructive. The added value is moderate.
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 sentences, no unnecessary words. The first sentence states the purpose, the second provides technical context. It is front-loaded with the key 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?
The description covers the basic intent but lacks completeness for a mutation tool. It does not mention the output schema (though one exists), nor does it explain what happens after setting the default (e.g., effect on secrets). The optional body parameter is left ambiguous. For a simple operation, it is minimally adequate but could be improved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has two parameters: 'path' (with 'id') and 'body'. The description only clarifies that 'id' is the config ID (from the API path), but does not explain the 'body' parameter, which has no schema. Schema description coverage is 50%, so the description should compensate, but it fails to add meaningful detail about what the body contains or when it is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Set') and the resource ('default secret provider configuration'). It distinguishes from sibling tools like 'pc_patch_secret_provider_configs_by_id' (update) and 'pc_delete_secret_provider_configs_by_id' (delete) by focusing on setting the default. The inclusion of the API path further clarifies 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?
The description does not provide any guidance on when to use this tool versus alternatives. It lacks context about prerequisites, such as needing an existing secret provider config, or when to prefer this over patching or creating configs. No explicit when-to-use or when-not-to-use information is 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 provide destructiveHint=true and readOnlyHint=false, indicating mutation. The description adds that the path is allowlisted and external inputs are rejected, which is useful security context. No contradiction with annotations, but the description does not disclose further side effects (e.g., what happens on success/failure). A 3 is appropriate given annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded: first sentence states purpose, second adds a crucial security constraint. No unnecessary words; every sentence adds 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?
Despite having an output schema, the description is incomplete for a tool with 5 parameters (0% schema coverage) and a destructive nature. It omits parameter explanations, return value behavior, and instructions on how to construct calls. The existence of many sibling tools also makes usage guidance insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides zero information about any of the 5 parameters (body, path, query, multipart, operation). It does not explain their roles, format, or constraints (e.g., operation is a string from a list). This is a critical gap for a tool with no enum hints or 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 it calls one exact operation from paperclip_list_operations, distinguishing it from the listing tool and the many specific operation tools. It also specifies security constraints (allowlisted path, no caller-provided URLs/headers/etc.), making its purpose precise.
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 tells when to use: after listing operations, call one exactly. It also states what not to provide (caller-provided inputs). However, it does not explicitly mention when to prefer this tool over the many specific operation tools, nor does it mention prerequisites like having listed operations first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that the operation is a GET request and requires 'board_or_agent' authorization, which provides behavioral context beyond what annotations convey. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) and front-loads the purpose. It includes the HTTP operation and authorization, which is useful. Every sentence adds value, but it could be more structured (e.g., separate lines). Equivalent to MID tier.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with an output schema, the description covers the purpose, HTTP method, and authorization. However, it lacks explanation of what a config schema is and when to invoke it (e.g., after getting adapter list). It does not mention the required 'type' parameter explicitly. Given the complexity is low, it is adequate but not thorough.
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 1 parameter (path.type) with 0% document coverage. The description does not explain what 'type' represents or how to use it. It only says 'Get adapter config schema', which implies the type is the adapter type, but offers no syntax or examples. Schema coverage is low, so the description should compensate, but it does not.
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 tool name and description clearly state it retrieves the configuration schema for a specific adapter type. This is distinct from sibling tools like pc_get_adapters (list adapters) and pc_get_adapters_by_type (get adapter details), which are about the adapters themselves, not their config 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 no guidance on when to use this tool versus alternatives. It does not mention context, prerequisites, or mention excluded scenarios. The agent is left 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds the HTTP method (GET) and authorization class ('board_or_agent'), which are useful behavioral traits not in annotations. No contradictions found.
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 concise with two sentences, front-loading the core purpose. The second line provides additional context (HTTP operation and authorization). While brief, it avoids unnecessary verbosity, though it could include more behavioral info without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single-parameter GET with output schema defined), the description is minimally adequate. However, it does not explain what the instructions file contains or how it relates to the instructions bundle tool. More context would help an agent avoid confusion with similar tools.
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 coverage is 0%, so the description must compensate. It mentions the Paperclip operation URL '/api/agents/{id}/instructions-bundle/file', which implicitly clarifies that the required 'path.id' parameter is the agent ID. This adds meaningful context 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 'Get agent instructions file', which specifies the verb and resource. However, it does not differentiate from sibling tools like pc_get_agents_by_id_instructions_bundle, which retrieves the entire bundle. The operation and authorization details add context but do not clarify the 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?
The description provides no guidance on when to use this tool versus alternatives like pc_get_agents_by_id_instructions_bundle. There is no mention of prerequisites, context, or when not to use the tool. With many sibling tools, this omission is a significant gap.
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, idempotentHint, and destructiveHint, so the agent knows this is a safe read operation. The description adds the HTTP method (GET), endpoint, and authorization class (board_or_agent), which provides some behavioral context but does not disclose additional traits like rate limits or output handling beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of one core sentence and two lines of technical details (HTTP method, endpoint, auth class). Every sentence adds value, with no fluff 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?
Given the simplicity of the tool (1 parameter, output schema provided, annotations covering safety), the description is mostly complete. It lacks a description of the 'companyId' parameter and does not explain what 'decision training examples' are, but the output schema covers return values. Overall, adequate for a simple read tool.
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 no descriptions (0% coverage), and the description does not explain the single required parameter 'companyId'. A user must infer its meaning from context. Since there is only one parameter and no schema descriptions, the description should compensate but fails to do so.
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 'Export decision training examples as JSONL', specifying the verb (export), resource (decision training examples), and format (JSONL). It distinguishes this tool from other decision training tools like pc_get_companies_by_company_id_decision_training (which lists training examples) and pc_post_companies_by_company_id_decision_training (which creates them).
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 does not provide any guidance on when to use this tool versus alternatives, such as when to export vs. list or create training examples. It omits prerequisites, context, or exclusions, leaving the agent without decision-making support.
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, destructiveHint=false, which fully cover safety. The description adds the HTTP method (GET) and authorization class ('board_or_agent'), providing minor context but no additional behavioral traits beyond what annotations already convey. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short, consisting of a title repeat and one additional line about the endpoint and auth class. It is not verbose, but it could include more useful information in the same space (e.g., what a label is, any ordering). It is efficient but slightly under-specified.
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 (not provided) which may describe return values, so the description can be lighter. However, it lacks any mention of filtering, pagination, or the nature of labels. For a simple list tool, this may be adequate, but a bit more context (e.g., 'Returns all labels for the given company') would make it more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning the description does not explain the single parameter 'path.companyId'. Although the purpose is simple and the parameter name is suggestive, the description does not explicitly state that companyId identifies the company whose labels are to be listed. With only one parameter and 0% coverage, the description should compensate but does not.
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 'List labels in a company', which is a specific verb-resource pair. The title and first line repeat this, making the purpose unmistakable. The tool's name includes 'get' and 'labels', reinforcing that it is a list operation, and it is distinct from sibling label tools like create and delete.
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 the HTTP endpoint and authorization class but does not explicitly guide when to use this tool versus alternatives. While the name and title imply listing, there is no mention of scenarios or exclusions (e.g., 'Use this to list labels; to create or delete, use other tools'). The context signals show related label tools, but the description itself lacks usage 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the HTTP method (GET) and authorization class (board_or_agent), providing useful behavioral context 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 description is concise with only two sentences, front-loading the purpose. However, it could be better structured by separating the purpose from technical details (operation, auth). No redundant 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?
For a simple GET returning SVG, the description covers the purpose and basic behavior. However, it is missing parameter explanations and output format details. The presence of an output schema partially mitigates this, but the description should be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% parameter description coverage. The description does not explain the companyId parameter or provide guidance on its value. Despite the parameter being self-explanatory by name, the description should add meaning beyond the schema, which it fails to do.
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 'Get org chart as SVG', indicating the verb (get) and resource (org chart as SVG). This distinguishes it from sibling tools like pc_get_companies_by_company_id_org (likely JSON) and pc_get_companies_by_company_id_org_png (PNG).
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 lacks context such as when SVG is preferred over PNG or JSON, or any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the specific HTTP method (GET) and authorization class (board_or_agent), which supplement the annotations (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false). It provides useful behavioral context beyond what annotations already convey, though it does not detail response format or side effects beyond the safe read nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences with no superfluous content. It front-loads the core purpose and immediately follows with the API operation details. Every word is justified.
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 simplicity (one parameter, clear annotations, and an output schema), the description covers the basic operation and auth requirement. However, it lacks parameter explanations and usage context relative to sibling tools, which is a gap for a complete 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 has a single 'path' object with three required string properties (companyId, skillId, runId) but lacks descriptions at the property level (0% coverage). The description partially compensates by showing the URL template with these IDs, indicating their roles, but does not explain what they represent or provide format constraints.
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 'Get a skill test run' which clearly indicates the operation is a retrieval of a specific test run. The title and name further reinforce this, but it does not explicitly distinguish from sibling tools like listing test runs, though the resource path and verb make it implicitly 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?
No guidance is provided on when to use this tool versus alternatives such as listing test runs or deleting a test run. The description only includes an authorization class requirement, but does not explain 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?
Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the authorization class and HTTP method but does not disclose additional behavioral traits such as pagination behavior or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. It front-loads the action and provides the HTTP path and authorization class, making every sentence 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 (list with pagination and filters), the description lacks detail about what 'bounded execution workspace overview rows' represent, how to use pagination, or what the output contains. The output schema exists but is not described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It mentions companyId only implicitly in the path template but does not describe query parameters (limit, offset, status, projectId). Users cannot understand the function of these parameters from the description alone.
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 bounded execution workspace overview rows for a company. The verb 'List' and resource 'workspace overview rows' are specific and distinguish this from other company-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. The authorization class 'board_or_agent' gives some context on who can use it, but there is no comparison with sibling tools or scenarios for alternative selections.
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, destructiveHint=false, indicating a safe read operation. The description adds the API endpoint and authorization class, which provides operational context but does not disclose additional behavioral traits 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 extremely concise: two sentences with no wasted words. The first sentence states the purpose, and the second provides operational context. Every sentence 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?
Given there are no parameters and an output schema exists, the description is sufficiently complete. It clearly states the operation and resource, and the output schema handles return value documentation. It could mention the return format, but it's not necessary.
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?
There are no parameters, so the schema coverage is 100% trivially. With zero parameters, the baseline is 4, and the description appropriately adds no redundant parameter information.
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 'List scheduler heartbeats', which is a clear verb+resource combination. It specifies the resource but does not elaborate on what 'scheduler heartbeats' are, leaving slight ambiguity. However, it distinguishes itself from sibling tools like pc_get_heartbeat_runs_by_run_id which focus on individual runs.
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. With many sibling tools, the absence of usage context makes it harder for an agent to decide when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false. Description adds that it is a GET operation with public authorization, which aligns with annotations and provides additional context. No contradictions, but no detailed behavioral disclosure (e.g., error responses, latency).
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?
Description is very concise: three short lines. It front-loads the purpose and adds operation details. Could be slightly more informative without bloat, but overall efficient.
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 annotations (read-only, idempotent) and existence of output schema, the description is reasonably complete. It adds the HTTP method and auth class. Could mention that it returns gateway details, but not essential since output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has one required parameter 'gatewayPublicId' with 0% description coverage. The description implicitly explains it via the path template '{gatewayPublicId}', but does not explain its meaning, format, or constraints beyond being the public ID.
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?
Title and description clearly state the tool describes a public MCP gateway endpoint. The name 'pc_get_mcp_gateways_by_gateway_public_id' is specific and differentiates from siblings that deal with companies, skills, or other entities.
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 on when to use this tool versus other gateway-related tools like 'pc_post_mcp_gateways_by_gateway_public_id' or 'pc_get_companies_by_company_id_tools_gateways'. The description only provides the HTTP method and path, not context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the HTTP method and authorization class, which reinforces these traits but does not provide significant new behavioral context 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?
Two sentences: one clear purpose and one technical detail. No redundant information. Could be slightly more concise by omitting 'Paperclip operation:' or merging sentences, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only listing tool with an output schema, the description covers the essential operation, path, and authorization. However, it lacks details on sorting, filtering, or pagination that might be relevant for 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 input schema has 0% description coverage, so the description must compensate. The path '/api/secrets/{id}/access-events' implies that 'id' is a secret identifier, but no explicit definition, format, or constraints are given. This adds partial meaning but is insufficient for complete clarity.
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 'List secret access events' with a specific verb and resource. The included HTTP method and path further clarify the operation, distinguishing it from other secret-related tools like pc_get_secrets_by_id_usage.
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 on when to use this tool versus alternatives. There is no mention of prerequisites, context, or exclusions, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and destructiveHint annotations, the description adds that it is a GET operation with authorization class 'board_or_agent', providing useful behavioral context about how the tool is accessed and who can use it.
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 very concise (two sentences) and front-loaded with the purpose. However, it could be slightly more informative about what 'available skills' entails without sacrificing brevity.
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 low complexity (no parameters, rich annotations, output schema exists), the description is adequate but minimal. It lacks explanation of how this tool differs from similar siblings, which is a gap for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is 100%. The description adds no parameter-specific information, but with zero parameters, the baseline of 4 is appropriate.
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 'List available skills', which is a clear verb+resource combination. However, it does not distinguish this tool from siblings like pc_get_skills_catalog or pc_get_skills_index, which may have overlapping purposes.
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 only states what the tool does, without any context about when it is appropriate or not.
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 destructiveHint=true, so the destructive nature is already flagged. The description adds the authorization class 'board', but does not elaborate on side effects (e.g., whether stopping terminates processes gracefully, if it's safe, or what happens to in-progress work). The behavioral context is adequate given annotations, but could be improved.
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 concise, consisting of two sentences. The first sentence front-loads the core action. However, the second sentence about the API operation may be less relevant to an AI agent, but does not detract significantly. It could be streamlined further.
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 simplicity (stop action), the description is mostly adequate. However, it does not mention the output schema (which exists) or whether the operation is synchronous. Combined with missing parameter descriptions, the agent may lack complete context for successful invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers the 'body' parameter with a description, but the required 'path' parameters (companyId, id) have no descriptions. The tool description does not explain these parameters or their purpose. With schema coverage at 50%, the description should compensate but fails to do so, leaving the agent to infer parameter meanings.
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 'Stop a local stdio MCP runtime slot', using a specific verb and resource. This distinguishes it from sibling tools like start or list operations, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides the API endpoint and authorization class, giving some context, but does not explicitly state when to use this tool versus alternatives (e.g., when a runtime slot is running and needs to be stopped). Nor does it offer guidance on when not to use it. Usage is implied by the tool's 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?
Adds that it's a POST operation (mutating) and authorization requirement. Annotations already indicate non-readonly and non-destructive, so description adds marginal value.
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?
Extremely concise with two sentences, no redundant information.
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?
Minimal description; fails to leverage output schema or provide context on enabling semantics. Could benefit from more details on effects or prerequisites.
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?
Description does not mention parameters. Schema has 50% description coverage; fails to add meaning for the body or path 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?
Clearly states 'Enable a plugin' with verb and resource. Distinguishes from sibling tools like disable and delete by name and description.
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?
Does not provide explicit when-to-use or when-not-to-use guidance. Mentions authorization class but no comparison with alternatives like disabler or delete.
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, destructiveHint=false. Description adds the HTTP method and authorization class, providing some additional context but not rich behavioral details beyond what annotations offer.
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?
Extremely concise with two short sentences. Essential information is front-loaded. 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 readonly operation with no parameters, the description is adequate. It covers the key points, especially given that annotations and output schema exist. Could mention typical use cases but not required.
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?
No parameters exist and schema coverage is 100%, so baseline 3 is appropriate. Description adds no parameter info as none 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 'Get current session' which is a specific verb and resource. The tool name and title align perfectly, and it is distinct from siblings as the only auth session tool.
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 on when to use this tool versus alternatives. Does not mention that this is a safe, read-only operation (though annotations indicate that).
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, idempotentHint, and non-destructive hint, so the safety profile is clear. The description adds the HTTP method and authorization class, but does not disclose pagination, limits, or what constitutes a 'live run'. With annotations, the description provides marginal extra 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 two sentences: one for purpose, one for operation details. Every sentence is informative and there is no redundancy. It is front-loaded with the core action and efficiently adds technical 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?
Given the tool has an output schema (so return values need not be described), one parameter, and safety annotations, the description covers the essential usage. It provides the HTTP method, path, and authorization class. However, it could be more complete by noting potential pagination or clarifying what 'live runs' means in this context. Overall, it is nearly complete for a simple list 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 0%, so the description should compensate. It includes the path template 'GET /api/companies/{companyId}/live-runs', which clarifies that companyId is a path parameter. However, it does not describe the parameter's purpose, format, or constraints beyond the schema's required string type. This adds some context but not enough to reach a higher score.
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 'List live runs for a company' which is a clear verb+resource combination. It provides the exact HTTP method and path, adding specificity. While it doesn't explicitly distinguish from sibling tools like pc_get_issues_by_issue_id_live_runs, the companyId parameter implies the scoping difference, so purpose is clear but not perfectly differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes the HTTP operation and authorization class ('board_or_agent'), giving basic when-to-use context. However, it does not mention when to avoid this tool or suggest alternatives (e.g., scoping by issue). The guidance is adequate but minimal.
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, etc. The description adds the HTTP method (GET) and authorization class (board_or_agent), providing extra behavioral context beyond annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise but somewhat redundant as it repeats the title. The second line with HTTP method and auth class is useful. Could be improved by removing the duplicate and adding more context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one parameter and an output schema, the description is minimally adequate. It states the purpose and provides the auth class, but lacks details on the structure of the returned org chart data and the parameter significance.
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?
Input schema has one parameter (path.companyId) with 0% description coverage. The description does not explain what companyId represents (e.g., 'the ID of the company to get the org chart for'), leaving the agent to infer its meaning from the tool name.
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 'Get org chart data', which is a specific verb and resource. It distinguishes from sibling tools like pc_get_companies (list companies) and pc_get_companies_by_company_id (company details) by targeting hierarchical org structure.
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 when-to-use or when-not-to-use guidance is given. The description only states the function; usage context is implied by the name and sibling tools, but no alternatives or exclusions 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?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the HTTP method (GET) and authorization class (board_or_agent), which are not in annotations. However, it does not discuss error behavior, pagination, or other runtime aspects.
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 very concise with two sentences. It is front-loaded with the core purpose and adds the HTTP method and auth class. While efficient, it could include more detail without becoming lengthy.
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 presence of an output schema and clear annotations, the description sufficiently conveys the tool's function. It explicitly states it lists interactions for a specific issue. Minor gap: does not explicitly state that the 'id' is the issue ID, but that is easily inferred.
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 0% description coverage, and the description does not explain the 'path' parameter or the 'id' field. Although the parameter is obvious from the tool name and context, the description fails to add explicit meaning to 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 it lists issue thread interactions, using a specific verb 'List' and resource 'issue thread interactions'. It distinguishes from siblings like pc_post_issues_by_id_interactions (create) and pc_get_issues_by_id_interactions_by_interaction_id_accept (accept a specific interaction).
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 listing interactions but provides no explicit guidance on when to use this vs alternatives, such as when to use pc_get_issues_by_id for issue details or other interaction-related tools. No exclusions or context 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, which indicate a safe, read-only operation. The description adds the specific HTTP endpoint (GET /api/plugins/ui-contributions) and authorization class ('board'), which provides useful context beyond the annotations. However, it does not elaborate on pagination, rate limits, or the nature of the response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very brief: two sentences. The first sentence essentially repeats the title. The second sentence adds technical details (HTTP path and auth). While concise, it could be more efficient by merging or removing redundancy. Still, it is clearly structured and 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 has an output schema (not shown), the description does not need to explain return values. However, it lacks context such as the scope of the listing (e.g., all plugins or installed ones) or whether it requires specific permissions beyond the hinted authorization class. The description is adequate but incomplete for an AI agent to fully understand when and how to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so schema description coverage is 100%. The description does not need to add parameter semantics. It succinctly notes that the tool requires no additional input. The baseline for zero-parameter tools is 4, and the description meets 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 title 'List plugin UI contributions' and the description's first sentence clearly state the action (list) and resource (plugin UI contributions). This is a specific verb+resource combination that distinguishes it from the many sibling tools that deal with plugins, companies, issues, etc. The name and description align perfectly.
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 lacks any guidance on when to use this tool versus alternatives. It does not mention when this listing is appropriate (e.g., discovering available UI contributions from plugins) or what specific context it covers (e.g., global vs per-company). No exclusions or alternatives are 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, which accurately describe the tool's safety profile. The description adds no additional behavioral context beyond the endpoint, so it does not exceed what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long and front-loads the purpose. Every piece of information earns its place, with no extraneous text. The endpoint and auth info are concisely appended.
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 presence of an output schema, the description need not explain return values. However, with no parameter descriptions and no usage guidance, the description is minimally adequate for a simple read operation but lacks depth for a fully self-contained definition.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions exist. The tool description fails to explain what 'id' (routine ID) and 'threadId' (annotation thread ID) represent, leaving the agent without crucial context for correct invocation.
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 'Get a routine description annotation thread', which is a specific verb-resource pair. It distinguishes itself from sibling tools like 'pc_get_routines_by_id_description_annotations' (which gets all annotations) by including 'by_thread_id' in the name and description.
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 the endpoint and authorization class but does not explicitly state when to use this tool versus alternatives like the parent list endpoint or the patch/post endpoints. The name implies specificity, but no direct guidance is 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 destructiveHint: true, so the agent knows this is destructive. The description adds 'Authorization class: board' which is useful, but it does not detail side effects or state changes beyond what annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. The first sentence states the purpose, the second provides API details. Exceptionally 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?
While the tool has an output schema (not described), the description lacks information on prerequisites, error conditions, or the effect of disabling a plugin. For a simple action this is acceptable, but more detail would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no meaning to parameters. The input schema has 50% description coverage (body is described, pluginId is not). The description does not explain the pluginId or the optional body payload.
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 explicitly states 'Disable a plugin', which is a specific verb+resource. The title matches this. Among sibling tools, there are enable and delete plugin tools, making this clearly distinct.
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 the API endpoint and authorization class but does not give explicit when-to-use or when-not-to-use guidance. The name and title imply disabling versus deleting, but no alternative tools 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?
Annotations already provide destructiveHint=true and other flags. The description adds the HTTP DELETE method and authorization class, but does not disclose side effects or additional behavioral context beyond what annotations convey.
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 sentences stating the purpose and operation details. No extraneous information, every sentence 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 reset operation, the description provides purpose, HTTP method, and authorization class. An output schema exists, so return values need not be described. However, it lacks explanation of 'open default' and any prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 50%, the description adds no parameter details beyond the schema. The path.companyId parameter lacks any description, and the description does not clarify its purpose or format.
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 title and description clearly state 'Reset the company skill policy to the open default', specifying a clear verb (reset) and resource (company skill policy). This distinguishes it from sibling tools like GET (retrieve) and PUT (update).
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 resetting to the open default, but does not explicitly state when to use this tool versus alternatives like GET, PUT, or POST evaluate. No exclusions or alternate scenarios are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint and idempotentHint. The description adds the authorization class, which is behavioral context beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) and efficient, but it could include more detail without losing conciseness. It front-loads the core purpose.
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 destructive operation with an output schema, the description lacks details on deletion consequences or idempotency behavior. It is minimally complete but leaves gaps for an agent.
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 50%, but the description does not clarify the parameters. The body parameter is described as 'optional JSON compatibility payload' which is vague, and the required path.id has no explanation.
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 title and description clearly state 'Delete a project'. The tool name indicates it operates on a project by ID, and the HTTP method DELETE is given, distinguishing it from read/update tools among siblings.
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 mentions authorization class ('board_or_agent') but does not provide explicit guidance on when to use this tool vs alternatives like archiving or patching. Context is implied but not 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 already declare readOnlyHint, destructiveHint, and idempotentHint, so the safety profile is clear. The description adds the authorization class 'board_or_agent', providing extra context. However, it does not disclose other behavioral traits like rate limits or what happens if no secrets are found.
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?
Extremely concise, two sentences. The first sentence states the purpose, the second provides technical details (HTTP method, path, auth). Could be improved by front-loading the purpose and moving technical details to a separate line, but overall efficient with 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?
Given no parameters, rich annotations, and existence of an output schema, the description is mostly complete. It could mention that the secrets are returned as a list or that they are scoped to the current agent run, but this is already implied. The description adds the authorization class, which is useful.
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 schema coverage is 100%. The description correctly mentions no parameters are needed, which is sufficient. Per guidelines, baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists secrets accessible to the current agent run, using a specific verb and resource. It distinguishes from sibling tools like pc_get_companies_by_company_id_secrets by specifying the scope ('current agent run'). The inclusion of the HTTP endpoint and authorization class adds 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?
No guidance on when to use this tool versus alternatives. It does not mention when not to use it or point to sibling tools like pc_get_companies_by_company_id_secrets for company-level secrets. The agent must infer usage from the title 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?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the HTTP endpoint and authorization class, but these are minimal behavioral traits beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is composed of two concise, front-loaded sentences. No extraneous information is present; every sentence 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?
The tool has an output schema, so return values do not need to be described. The description provides the endpoint and auth class, and the purpose is clear. It could mention what 'details' include, but is adequate for a simple retrieval.
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 one parameter (token) with 0% description coverage. The description does not explain the token parameter's format or meaning beyond what is implied by the schema. Since coverage is low, the description should compensate but does not.
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 'Get board claim details by token', combining a specific verb ('Get') with a specific resource ('board claim details') and identifier ('token'). This distinguishes it from siblings like pc_post_board_claim_by_token_claim which is for claiming.
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 mentions 'Authorization class: public', indicating it requires no special authentication. However, it does not explicitly state when to use this tool versus alternatives, nor does it provide 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, destructiveHint=false, idempotentHint=true. The description adds authorization class 'board_or_agent' but no further behavioral traits. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences: one repeats the title, the other adds endpoint and authorization. Concise but the first sentence is redundant.
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 count tool with one parameter and an output schema, the description covers the resource, method, and authorization. Return value details are left to 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?
Schema description coverage is 0%, but the only parameter 'companyId' is self-explanatory from the endpoint path. The description does not elaborate on it, which is acceptable but not compensatory.
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 'Count issues in a company', which is a clear verb+resource. It differentiates from sibling tools like pc_get_issues (list issues) and pc_get_companies_by_company_id_issues (list issues for a company) by focusing on counting.
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 when-to-use or alternatives are mentioned. The purpose implies it should be used when only the count is needed, but no direct guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds the HTTP method (GET) and authorization class ('board'), which provides behavioral context beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and to the point, with no fluff. However, the first line is redundant with the title, slightly reducing efficiency.
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 provides essential behavioral info but omits details about the response format, pagination, or filtering. Given the presence of an output schema, the description could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the single required parameter (companyId). It only mentions the path indirectly, failing to add 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 'List tool policies' uses a specific verb and resource, clearly distinguishing it from siblings like create, delete, and update operations. The title reinforces this 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?
No explicit when-to-use or when-not-to-use guidance is provided. However, as the only listing tool among related CRUD siblings, usage is implied. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds the HTTP GET method and authorization class ('board_or_agent'), providing context beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two sentences) and relevant. It could combine the first sentence with the second, but no extraneous information is present.
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 that an output schema exists, return values are not required. However, the description does not mention what the tool returns (the full environment object) or any prerequisites. With 0% parameter description coverage, completeness is adequate but not thorough.
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 sole parameter 'path.id' is not described in the schema (0% coverage) and the description does not explain its purpose (e.g., 'the environment ID'). Since the schema provides no description, the description must compensate but fails to do so.
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 'Get an environment', which is a specific verb+resource. It matches the title and distinguishes from siblings like pc_get_companies_by_company_id_environments (which lists environments) and other CRUD tools. The HTTP method and authorization class reinforce 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 description implies single-environment retrieval via the name and URL pattern, but it does not explicitly state when to use this tool versus alternatives (e.g., listing environments). No when-not-to-use or exclusion 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 description's burden is reduced. It adds the authorization class 'board' but little else about effects or constraints. The description does not contradict annotations, but adds minimal 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, making it concise. It front-loads the core purpose and then adds technical details. However, the second line about Paperclip operation and authorization class may be unnecessary for the agent, but it does not harm 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?
For a simple read-only tool with no parameters and an existing output schema, the description sufficiently conveys the tool's function. It does not explain the return value, but the output schema covers that. The description is adequate for the tool's complexity.
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 no parameter descriptions are needed. The description does not add any parameter information, but with 0 parameters and 100% schema coverage, a 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 'Get general instance settings', which is a specific verb-resource pair. It distinguishes from siblings like pc_patch_instance_settings_general (update) and pc_get_instance_settings (possibly broader scope), 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. It does not mention when not to use it, nor does it reference sibling tools like pc_get_instance_settings or pc_patch_instance_settings_general. The agent is left without context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds the authorization class 'board_or_agent' and HTTP method, providing extra behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two sentences) and front-loaded with the purpose. The repetition of the title is minor redundancy but doesn't harm clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with output schema, the description covers basic purpose and auth, but lacks parameter explanation. It is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter `path.id` has no description in schema or in the tool description. Schema coverage is 0%, and the description fails to explain what the id represents (routine ID), leaving the agent without guidance.
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 it lists routine description annotation threads, and the endpoint path confirms this. It is specific and distinct from sibling tools like create or get single thread.
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 guide when to use this tool versus siblings like pc_post_routines_by_id_description_annotations. Usage context is implied by the naming but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds the authorization class 'board_or_agent', providing useful context beyond annotations about who is allowed to perform the deletion.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action, followed by endpoint and auth info. No fluff or repetition; 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?
Adequate for a simple DELETE operation, but missing parameter descriptions and usage context. Output schema exists but is not referenced. The description covers purpose and auth but lacks guidance on constructing the path, which could lead to errors.
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 50% with only the body parameter having a vague description. The description does not explain the path parameters (companyId, skillId, commentId) beyond their names, leaving the agent without semantics for constructing valid requests.
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 'Delete a skill comment' and provides the HTTP DELETE endpoint. This distinguishes it from sibling tools like delete skill (pc_delete_companies_by_company_id_skills_by_skill_id) and other comment operations (post, patch).
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 provide explicit guidance on when to use this tool vs alternatives like patch or get comments. It only implies usage by naming the operation, but lacks prerequisites, when-to-use, or when-not-to-use information.
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, idempotentHint, and destructiveHint:false, so the safety profile is well-covered. The description adds the HTTP endpoint (GET /api/auth/profile) and authorization class ('board'), which provides useful implementation details beyond the annotations. However, it doesn't discuss any side effects or error conditions.
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, consisting of just two lines. It front-loads the purpose and includes the key implementation detail. Every word earns its place with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, strong annotations, and an output schema, the description is adequate. It states the operation and endpoint, which is sufficient for a simple read-only profile retrieval tool. A minor gap is that it doesn't explicitly state what is returned (e.g., user profile fields), but the output schema likely covers that.
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 and schema description coverage is 100%, so the description bears no burden for parameter documentation. A baseline of 4 is appropriate as the description adds no param-related information but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get current user profile', which is a specific verb and resource. It unambiguously identifies the tool's purpose and is distinct from sibling tools like pc_get_sidebar_preferences_me or pc_get_agents_me.
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 when not to use it, prerequisites, or context. For example, it doesn't clarify that this is the tool to use when needing the authenticated user's profile info, as opposed to pc_get_agents_me or other profile-related 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 provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds the HTTP method (GET) and endpoint, plus authorization class, which is useful but not extensive. 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?
Two very short sentences, front-loaded with the purpose. 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 zero-parameter tool with output schema and clear annotations, the description is sufficient. It covers purpose and a few technical details, leaving return values to the schema.
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?
No parameters exist, so description cannot add value here. Schema coverage is 100%, baseline 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 explicitly states 'List board API keys', which is a specific verb-resource combination. Sibling tools include pc_post_board_api_keys and pc_delete_board_api_keys_by_key_id, so this tool's purpose is clearly distinct.
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 on when to use this tool versus alternatives. No exclusions, prerequisites, or context for when listing API keys is appropriate.
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 and idempotentHint. The description adds the HTTP method and endpoint, plus authorization class 'board', which provides some context beyond annotations. However, it does not detail what happens when no session exists or the exact response structure.
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?
Extremely concise: two short sentences. First sentence makes purpose immediately clear. Second sentence provides the endpoint and authorization context without any fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and the existence of an output schema, the description covers the essential purpose and technical details. The authorization class provides useful context. Minor gap: no mention of expected output or potential error states, but the output schema likely handles that.
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?
No parameters in schema, so baseline is 4. The description accurately reflects this and adds no unnecessary information. The schema coverage is 100%.
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 'Get current CLI auth session' as a specific verb+resource combination. It is easily distinguished from sibling tools that modify auth (e.g., pc_post_cli_auth_challenges) based on the read-only nature.
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 on when to use this tool versus other CLI auth tools. While 'Get' implies read-only, there is no mention of prerequisites (e.g., having an active CLI session) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds the HTTP method (GET) and authorization class (board_or_agent), which are useful beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the purpose. No extraneous information. Every word serves a purpose.
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 simple (list runs), and an output schema exists, so return values are covered. However, the lack of parameter documentation and usage guidance leaves gaps. A minimally viable description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so parameters are entirely undocumented in the schema. The description only mentions companyId in the endpoint string but does not explain its meaning, format, or constraints. It fails to compensate for the missing 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 title and description explicitly state 'List heartbeat runs for a company,' which clearly identifies the verb (list) and resource (heartbeat runs scoped to a company). This distinguishes it from sibling tools like pc_get_heartbeat_runs_by_run_id (single run) and pc_post_heartbeat_runs_by_run_id_cancel (cancel action).
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 listing, but provides no explicit guidance on when to use it vs. other heartbeat-run tools (e.g., get a specific run). No alternatives or exclusions are mentioned. The 'Authorization class' hint is peripheral.
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, destructiveHint, idempotentHint, and openWorldHint. The description adds value by specifying the exact HTTP method (GET) and endpoint path, plus the authorization class. 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—two sentences that front-load the primary purpose. No extraneous words, and every sentence provides useful information.
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 presence of an output schema and helpful annotations, the description is adequate but lacks explanation of the required parameter. For a single-parameter tool, this is a noticeable gap, though the output schema compensates for return value details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain what the required 'id' parameter represents. The parameter name and context from sibling tools imply it is an environment ID, but the description itself fails to clarify 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 'List leases for an environment' which is a specific verb and resource. It distinguishes itself from sibling tools like pc_get_environment_leases_by_lease_id (which retrieves a specific lease) by focusing on listing all leases for an environment.
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 includes authorization class information, but provides no guidance on when to use this tool versus alternatives (e.g., when to list all leases vs. get a specific lease). No exclusions or context cues are present.
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 provide readOnlyHint, idempotentHint, destructiveHint. The description adds the HTTP method (GET) and authorization class ('board'), which gives slightly more context. 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 extremely concise (two sentences) with no filler. Every part contributes meaning: the purpose and the technical mapping.
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, parameterless, read-only tool with a declared output schema, the description provides enough context. It could mention the return format (list), but the output schema covers that.
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 no parameters and 100% coverage. The description adds value by specifying 'installed plugins', which clarifies the scope beyond the endpoint path.
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 explicitly states 'List installed plugins', which clearly identifies the verb and resource. Among siblings like pc_get_plugins_by_plugin_id or pc_get_plugins_examples, this tool is distinct for listing all installed plugins.
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. There is no mention of when to choose this over pc_get_plugins_by_plugin_id or other plugin tools, nor any exclusions or preconditions.
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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the HTTP method (GET) and authorization class (board_or_agent), providing useful context 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 extremely concise with two sentences and a blank line. No unnecessary words or repetition. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, return values need not be explained. However, the description lacks param documentation and could mention that the 'id' is the project ID. It covers the basic purpose and auth but not enough for a 0% schema coverage parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain the meaning of the required 'id' parameter. It only echoes the schema structure without adding semantic detail about what the 'id' represents (project ID).
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 explicitly states it gets an external object status summary for a project. The verb 'Get' and resource 'external object status summary for a project' are specific and clear. Among siblings, it is distinguished by focusing on projects rather than issues.
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 provide explicit guidance on when to use this tool versus alternatives like pc_get_issues_by_id_external_object_summary. It implies usage for project-level external object summaries, but lacks when-not or alternative suggestions.
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 provide destructiveHint=true, idempotentHint=true, readOnlyHint=false. The description adds that it's a DELETE operation and the authorization class 'board_or_agent', which is useful context beyond annotations. It doesn't fully clarify what 'unlink' means (e.g., does it delete the approval?), but adds value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states the purpose, second provides operation details. No wasted words, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete/unlink operation, the description covers purpose, operation, and authorization. It doesn't mention related siblings for linking, but the core usage is clear. Output schema exists, so return format isn't 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 50%, but the description does not explain parameters (id and approvalId) beyond their names. It doesn't compensate for the lack of schema documentation. The optional body is also unmentioned.
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 'Unlink an approval from an issue', with a specific verb and resource. The title and HTTP method (DELETE) reinforce this. It distinguishes from siblings like pc_post_issues_by_id_approvals (link) and pc_get_issues_by_id_approvals (list).
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. It implies use for unlinking a previously linked approval, but lacks criteria or context compared to other approval-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds the authorization class 'board_or_agent', which provides behavioral context beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first states the purpose, the second provides the HTTP method and authorization. No fluff, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description need not detail return values. It covers purpose, HTTP method, and authorization. Missing details like pagination or scope are acceptable for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the description does not add any parameter-level semantics. Although the companyId parameter is self-explanatory, the description fails to compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List skills for a company', which is specific and distinguishes it from sibling tools like pc_get_companies_by_company_id_skills_by_skill_id (single skill) and pc_get_skills_catalog (system-wide catalog).
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 includes the authorization class ('board_or_agent') but does not explicitly state when to use this tool versus alternatives, nor provide when-not or exclusion criteria. Usage is implied for listing skills for a company but lacks guidance on distinguishing from related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by disclosing the authorization class (board_or_agent) and the exact HTTP endpoint, providing useful behavioral context 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 extremely concise with two sentences, each providing distinct value: the core purpose and the endpoint/auth details. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, output schema exists), the description covers the essential purpose, endpoint, and auth. It does not explain what the status contains, but the output schema likely handles that. Minor gap: missing guidance on typical usage flow (e.g., polling after import submission).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions the jobId in the URL path, indicating the parameter represents an import job ID, but does not explain its format, source, or any constraints. This is minimal added 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 'Get company import job status', which is a specific verb-resource pair. The additional context of the HTTP method and authorization class further clarifies the operation. It distinguishes itself from sibling tools like `pc_post_companies_import` that create import jobs.
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 provide explicit guidance on when to use this tool versus alternatives (e.g., importing or previewing). Usage is implied as checking status after an import, but no exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the authorization class ('board_or_agent') and the exact HTTP method (GET) and path, providing useful context beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at two short sentences. No unnecessary words or repetition. Every sentence provides distinct information: the purpose and the REST endpoint with auth.
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 (one parameter, read-only). The description includes the endpoint and auth class. An output schema exists (not shown but indicated), so return value details are covered. Some might argue that the description could mention that the policy is effective (combining company-level and default), but it's not necessary given the low 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?
The input schema has one self-explanatory parameter (companyId) with 0% schema description coverage. The description does not mention the parameter, but the parameter is obvious from the tool name and context. Baseline 3 is appropriate given the trivial parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get the effective company skill policy', using a specific verb and resource. It distinguishes itself from sibling tools like pc_put_companies_by_company_id_skill_policy and pc_delete_companies_by_company_id_skill_policy by implying it is the read operation. The inclusion of the REST endpoint further clarifies the 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 mentions authorization class ('board_or_agent') but does not provide explicit guidance on when to use this tool versus its siblings (e.g., when to get vs update vs delete the skill policy). Usage context is implied but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare safe read-only, idempotent, non-destructive behavior. The description adds the HTTP method (GET) and public authorization, which is valuable beyond annotations. It does not mention error handling or response format, but output schema 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 extremely concise: one sentence for purpose, one for endpoint and auth. It front-loads the key action and resource. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only, single-parameter tool with annotations covering safety and output schema covering return values, the description is nearly complete. Minor gap: it could explicitly mention that this is the pre-acceptance retrieval endpoint, but that's implicit from the name and siblings.
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 0% schema description coverage, the description adds minimal semantic value—it reiterates that the token identifies the invite. It does not explain token format, expected length, or where to obtain it. Baseline 3 is appropriate given the low coverage and limited additional 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 clearly states the action ('Get') and the resource ('an invite by token'), with precise resource identification. It differentiates from sibling tools like pc_get_invites_by_token_logo and pc_post_invites_by_token_accept by focusing on the base invite retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes 'Authorization class: public', providing basic access context, but does not specify when to use this tool versus other invite-related tools (e.g., when to accept or revoke). There's no explicit guidance on alternatives 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, idempotentHint, openWorldHint, and destructiveHint=false. The description adds that the output is plain text and the authorization requirement, but does not disclose what the configuration contains, potential rate limits, or any side effects. Given the annotations, the description adds modest 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 only two sentences, front-loaded with the purpose and key operational details. Every part is necessary and there is no superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values are documented elsewhere. The description includes the HTTP endpoint and auth class. It could briefly mention typical content of the configuration, but given the tool's simplicity, it is nearly 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 no parameters (0 params, schema coverage 100%), so the description does not need to explain parameters. The baseline for 0 parameters is 4, and the description appropriately omits parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'agent configuration', the format 'plain text', and the intended use 'for LLM context'. This distinguishes it from the sibling pc_get_llms_agent_configuration_adapter_type_txt, which likely returns a different scope.
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 the HTTP method and authorization class, but does not explicitly state when to use this tool versus alternatives like pc_get_llms_agent_configuration_adapter_type_txt. Usage context is implied but lacks explicit guidance or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds context about returning operation keys and tool names, which is consistent with read-only discovery 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?
Two concise sentences front-loading key purpose and features. 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?
No output schema, so description should explain return values; it mentions 'operation keys and their generated pc_* tools' but lacks detail on format, pagination, or structure. With 4 params and no output schema, more completeness 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?
Description mentions 'filtered by tag or text' covering 'tag' and 'search' parameters, and 'bounded' covering 'limit'. Does not explain 'cursor' parameter, leaving a gap. Schema has 0% coverage, so description partially compensates.
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 discovers stable METHOD/path operation keys and their generated pc_* tools, which is a specific verb+resource. It distinguishes from many sibling pc_* tools that perform specific operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for discovering operations before calling them; mentions bounded results and filtering by tag or text. Doesn't explicitly exclude alternatives, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the authorization class ('board') and the HTTP method/path, providing useful additional behavioral context 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 extremely concise (two sentences) and front-loaded with the core purpose. Every part is relevant, with 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?
The tool has an output schema (not shown) and annotations covering safety, so the description is adequately complete for a simple read operation. However, it lacks explanation of what 'experimental instance settings' entail or how they differ from regular settings.
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 the description does not need to explain parameters. Schema description coverage is 100%, meeting the baseline for no-parameter tools.
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 retrieves experimental instance settings, matching the title and name. It distinguishes itself from siblings like pc_get_instance_settings and pc_get_instance_settings_general by specifying 'experimental'.
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 provide guidance on when to use this tool versus other settings tools (e.g., pc_get_instance_settings) or any exclusions. Usage context is only implied by the tool's 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?
Annotations already declare readOnly, idempotent, non-destructive. Description adds that it is a GET operation and requires 'board' authorization, providing useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences cover purpose and endpoint details. 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?
Given the presence of an output schema and annotations, the description sufficiently covers the tool's behavior. Could mention what activity data includes, but not critical.
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?
Only one parameter (connectionId) with no description; schema is clear but description adds no meaning. For a single parameter, this is adequate but could be improved.
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 'List tool connection activity' with a specific verb and resource. It distinguishes from sibling tools like get_connection (details) and get_usage (usage).
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 purpose is clear, allowing agents to infer when to use this tool (to list activity of a connection). However, it lacks explicit when-not or alternative 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds the HTTP method (GET) and authorization class (board_or_agent), providing useful behavioral context beyond what annotations offer.
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?
Extremely concise: two lines with no wasted words. The primary action is front-loaded ('List all adapters'), followed by supplementary technical 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?
Given no parameters, robust annotations (safety, idempotency), and an existing output schema, the description provides all necessary context: purpose, HTTP method, and authorization.
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?
Input schema has zero parameters with 100% schema coverage, so the description naturally has no param details. The baseline for 0 params is 4, and the description does not need to add more.
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 'List all adapters', specifying the verb (List), resource (adapters), and scope (all). This distinguishes it from sibling tools like pc_get_adapters_by_type which filters by 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 for listing all adapters, but lacks explicit guidance on when not to use it or alternatives. The sibling tool pc_get_adapters_by_type exists for filtered lists, but this is not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds the HTTP method (GET) and authorization class ('board'), providing context beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two short sentences. It provides the endpoint and auth class with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no parameters, rich annotations, and an output schema. The description adds the endpoint and auth class, making it fully complete for this simple listing 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 input schema has no parameters, so the description naturally does not add parameter details. Baseline 4 is appropriate as there is nothing to add.
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 explicitly states 'List companies' with the verb 'List' and resource 'companies'. It clearly distinguishes from siblings like pc_post_companies (create) and pc_get_companies_stats, as it is the basic list operation.
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 the endpoint and authorization class but no explicit when-to-use or when-not-to-use guidance. Usage is implied by the name 'list companies' and the context of being a simple GET without filters, but no alternatives 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?
Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds that it returns an error redirection, which is consistent and adds value, but no further behavioral details are 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?
Two sentences with no wasted words, efficiently conveying the legacy nature and error behavior.
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 it's a legacy error redirection with no parameters and annotations covering safety, the description is complete and sufficient for an agent to understand its purpose and effect.
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?
No parameters exist in the schema, and the description has 100% coverage. The description could not add parameter information, so baseline 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 it is a legacy tool that returns an error directing to the correct issues path, distinguishing it from sibling tools like pc_get_companies_by_company_id_issues.
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 implies this tool should not be used for direct issues retrieval but redirects to the correct path, providing clear context without explicit when-not-to-use statements.
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 adds context beyond annotations: it reveals the tool is legacy and returns an error. Annotations already indicate readOnly and idempotent, so the description complements these by explaining the actual behavior (error redirection).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no wasted words. The key information 'Legacy' is front-loaded, and the redirection path is clearly provided. Extremely concise and well-structured.
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 legacy tool that simply returns an error and redirects, the description is fully complete. It tells the agent what happens (error) and what to use instead. No additional details are 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?
There are no parameters and schema coverage is 100%, so the description does not need to add parameter details. 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 explicitly states 'Legacy — returns error directing to /api/companies/{companyId}/issues', clearly indicating the tool is deprecated and redirects users. This is a specific verb+resource+outcome.
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 not to use this tool by stating it returns an error and directs to another endpoint. While it does not explicitly say 'do not use', the context is sufficient for an agent to understand it should use the suggested alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, which cover behavioral traits. The description adds the specific HTTP method, endpoint, and authorization class, which provides additional transparency beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose. Every sentence adds value without redundancy. It is highly concise.
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 lack of parameters, existing output schema, and rich annotations, the description provides sufficient context for an AI agent to invoke the tool correctly. It covers what the tool does and how to access it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and the schema coverage is 100%. The description does not need to elaborate on parameters. 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 tool retrieves agent icon names as plain text, specifying the resource and format. It distinguishes itself from siblings like pc_get_llms_agent_configuration_txt by focusing on icons.
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 provide explicit guidance on when to use this tool versus alternatives. It mentions Authorization class but lacks when-to-use or when-not-to-use context. However, the purpose is clear enough to infer usage.
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, idempotentHint, and destructiveHint. The description adds the authorization class ('board_or_agent') and explains the behavior of the `view` parameter, which adds useful context 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 three concise sentences, each adding essential information: purpose, operation details, and parameter guidance. No unnecessary words, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown but indicated), the description does not need to cover return values. It covers the purpose, authorization, and key parameter behavior. It could mention pagination or sorting, but the annotations imply open-world semantics, so 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 0% description coverage, so the description must compensate. It explains the effect of the `view` parameter ('compact' for board issue-list row contract, default is broad contract). The required `companyId` is implied by the description and path, so no further explanation is strictly 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 'List issues in a company', which is a specific verb+resource combination. The name and title reinforce this, and the additional details about the `view` parameter help differentiate from other issue-related tools among the many siblings.
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 explains when to use the `view=compact` parameter for the board issue-list row contract, and notes the default behavior. However, it does not explicitly contrast with other issue-listing tools like `pc_get_issues` or `pc_get_issues_by_id`, leaving some ambiguity about when to choose this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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:

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

Score Badge

Copy to your README.md:

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

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