ALTR MCP Server

Official

by altrsoftware

Overview Schema Related Servers Score Discussions

Python

Remote

Server Quality Checklist

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

Latest release: v0.2.1
Disambiguation4/5
With 133 tools, there is potential for overlap, but each tool targets a distinct resource-action pair. Descriptions are detailed and clarify platform-specific differences. Some tools like `get_tags`, `get_tag_details`, `get_tag_details_by_group_id` are similar but descriptions distinguish them.
Naming Consistency5/5
All tools follow a consistent verb_noun pattern (e.g., create_classifier, get_classifiers, delete_database). No mixing of casing or verb styles is observed.
Tool Count1/5
133 tools is excessive for an MCP server. The server attempts to cover the entire ALTR platform with CRUD for many resource types, making it overwhelming for agents to navigate effectively.
Completeness4/5
The tool surface is broad, covering classification, masking, access policies, tokenization, FPE, sidecar management, auditing, and reporting. Minor gaps exist (e.g., no update for classifiers or collections), but core workflows are well supported.
Average 3.9/5 across 133 of 133 tools scored. Lowest: 2.6/5.
See the Tool Scores section below for per-tool breakdowns.
- 1 of 1 community issues answered or closed in the last 6 months
- 61 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under GPL 3.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description fails to disclose any behavioral traits such as idempotency, permissions, side effects, or rate limits. For a mutation tool, this is a critical gap.
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—but for a 7-parameter creation tool, it is arguably too brief and lacks contextual value. It is not wasteful 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 (7 parameters, 2 required, output schema present), the description is too sparse. It omits high-level context such as the role of a sidecar, prerequisites, or relationship to sibling tools like create_sc_sidecar_binding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage with descriptions for all 7 parameters, so the description need not add parameter info. It does not add any additional meaning beyond what the schema provides, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new sidecar' directly states the action (create) and resource (sidecar). It is specific and not a tautology, but it lacks differentiation from sibling tools that create other resources like agents or repos.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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, exclusions, or sibling tool comparisons are mentioned, leaving the agent 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states the action without any behavioral traits (e.g., idempotency, side effects, authentication requirements, rate limits). The agent creation process and implications are not 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 a single sentence, which is concise but lacks structure and sufficient detail for a tool with 5 parameters. Every sentence should add value; this one is too 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?
Despite having an output schema, the description is incomplete for a creation tool. It does not mention what is returned (e.g., agent ID) or any post-creation steps. The tool complexity and lack of annotations warrant more 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 input schema describes all parameters with 100% coverage, so the description adds no additional meaning beyond the schema. Baseline score is 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 'Create a new ALTR agent' uses a specific verb and resource, clearly indicating the tool's purpose. It distinguishes from sibling creation tools like create_sc_agent_task or create_sc_sidecar by the resource type, 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 is given on when to use this tool versus alternatives, such as create_sc_agent_task or create_sc_service_user. There is no mention of 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The destructiveHint annotation already indicates the operation is destructive, but the description does not add any additional behavioral context (e.g., irreversibility, cascading effects, or required authentication).
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?
Extremely concise (3 words), which is front-loaded, but lacks necessary context. Every word is functional, 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?
Given the output schema exists and annotations are present, the description is minimal. It does not address the variety of service users or distinguish from similar delete tools, making it less complete for an agent.
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 describes both parameters (repo_name, username) with coverage 100%. The description does not add further semantic meaning, so 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?
The description 'Delete a service user' clearly identifies the verb (delete) and resource (service user). However, it does not differentiate from sibling tools like delete_sc_repo_user or delete_sc_agent, missing an opportunity to specify 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 vs alternatives. There is no mention of prerequisites, permissions, or when to choose this over related delete 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 already indicate destructiveHint=true. The description adds nothing beyond confirming deletion, omitting important details like permanence, permission requirements, or side effects. With annotations present, the description should complement them, but here it merely restates the action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extraneous words, achieving high efficiency. However, it could be slightly more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although an output schema exists (not shown), the description fails to cover important contextual aspects for a destructive tool, such as irreversibility, required permissions, or typical use cases. Minimal guidance beyond the basic action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides clear descriptions for both required parameters (repo_name and username), achieving 100% coverage. The description adds no additional meaning beyond what the schema already conveys, so baseline 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?
The description 'Delete a repo user' clearly identifies the verb (delete) and the resource (repo user). It is specific enough among siblings like delete_sc_repo or delete_sc_agent, though it could be more precise by stating 'from a repository'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select 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. Sibling tools include create, update, list for repo users, and other delete tools, but the description lacks context about prerequisites (e.g., user must exist) or when this operation 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 set destructiveHint: true. The description only repeats the verb 'Delete' without disclosing any additional behavioral traits (e.g., what happens to associated data, whether the instance must be idle, or if the sidecar remains).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no waste, but it is overly terse and misses opportunities to add value while remaining 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?
The tool is a simple delete with two required parameters and an output schema. The description lacks context about effects, prerequisites, or return values, but for a straightforward delete it is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The tool description adds no extra meaning beyond what the schema provides, but the schema is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 'Delete a sidecar instance,' which is a specific verb+resource. However, it does not differentiate from sibling tools like delete_sc_sidecar or delete_agent_instance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select 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 list contains many delete operations, and this description provides 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true. Description adds no additional behavioral traits (e.g., permissions, idempotency, 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?
Single sentence, no wasted words. Could be more descriptive 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?
Output schema exists, so return values not needed. Description is minimal but adequate for a simple getter; could mention that it requires an existing agent.
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%; description for 'agent_id' as 'Agent UUID' is sufficient but adds no extra meaning beyond 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?
Description clearly states verb 'Get' and resource 'details for a specific agent', distinguishing it from list/create siblings. However, lacks specificity about what type of agent (e.g., SC 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 versus alternatives like get_agent_instance or list_sc_agents. No exclusion 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?
The description only restates the basic purpose, which is already implied by the name and the 'readOnlyHint' annotation. It adds no additional behavioral context such as filtering semantics, pagination behavior, or authentication 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 a single sentence that is concise and front-loaded. However, it is so brief that it sacrifices informational value for brevity, missing an opportunity to provide useful 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 omits important details about filtering (ports, sidecar_ids) and pagination (contiguous_id, limit). The agent cannot infer these capabilities from the description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not mention parameters, but the schema already provides adequate descriptions for all 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 action (list) and resource (sidecar bindings for a repository). However, it does not explicitly differentiate from the sibling tool 'list_sc_sidecar_bindings', which could cause confusion about when to use each.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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_sc_sidecar_binding' or 'list_sc_sidecar_bindings'. 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any side effects, authorization requirements, or behavioral traits beyond the basic registration action. It is a write operation, but the impact on the sidecar or system is unexplained.
Agents need to know what a tool does to the world before 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, consisting of one clear sentence. It is efficient but could benefit from additional 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 100% schema coverage, the description fails to explain the overall effect of registering a listener, such as how the sidecar will use it or any constraints. There is no mention of the output schema or return values, leaving the agent without full contextual understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters have descriptions in the input schema (100% coverage), so the schema already explains them. The description does not add extra meaning or context beyond what is in the schema, resulting in a baseline 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 'Register a listener port on a sidecar' clearly states the action (register) and the resource (listener port on a sidecar). It distinguishes from sibling tools like 'deregister_sc_sidecar_listener' and 'list_sc_sidecar_listeners' by indicating a create operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives, such as the need for a pre-existing sidecar or when to choose this over other registration methods. No prerequisites or context 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?
No annotations provided, and the description does not disclose behavioral traits such as permissions required, side effects, or whether the operation is reversible. The word 'Update' implies mutation, but no further detail 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence (4 words) and is efficient. It is not wasteful, but it may be too terse to fully inform usage. Still, it earns a high score for lack 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?
For a simple update tool with 2 parameters and an output schema (present), the description is minimally adequate. However, it lacks behavioral and usage context that would help an agent decide when to invoke it, especially given the many sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters (repo_name, description). The description adds no additional meaning beyond the schema, so it meets the baseline expectation for 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 'Update' and the resource 'a repository's description'. It is specific among sibling tools (e.g., update_sc_repo_user) as it focuses on the description field. However, it could be more precise by naming the repository type (source control).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select 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., create_sc_repo, delete_sc_repo). No prerequisites or context for usage. The description lacks any conditional or exclusionary 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?
No annotations are provided, so the description carries the full burden for behavioral disclosure. It only states the action without revealing side effects, permissions needed, whether the cancellation is reversible, or any notification behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It is efficient, though it could benefit from slightly more structure (e.g., listing required preconditions).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence 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 completeness. It does not explain what happens on success or failure, nor does it clarify that only the creator can cancel, which is important context for a tool with a 'you created' scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully documented in the input schema (100% coverage). The description adds no additional meaning, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Cancel' and identifies the resource as 'an access request you created,' which clearly distinguishes it from sibling tools like 'approve_access_request' or 'deny_access_request.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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 alternatives are appropriate. It lacks explicit context, exclusions, or references to 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?
No annotations are given, so the description must fully disclose behavior. It only states 'add a comment' without detailing idempotency, permissions, side effects, or return values, leaving critical gaps.
Agents need to know what a tool does to the world before 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, short and to the point. While efficient, it could be expanded slightly to improve completeness 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 lacks any mention of what the tool returns (e.g., the created comment or success status) and does not cover behavioral context like required permissions or error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all three parameters with descriptions, achieving 100% schema coverage. The description adds no extra meaning beyond the schema, so baseline score 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add a comment to a report instance' clearly specifies the action (add) and the resource (comment to a report instance), distinguishing it from sibling tools like create_report_definition or create_report_sign_off.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select 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 pin_report_comment or list_report_comments, nor any prerequisites like requiring an existing report instance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only says 'Create' without disclosing behavioral traits such as idempotency, permissions required, side effects, or reversibility. This is insufficient for behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and front-loaded. It efficiently states the purpose, though it could benefit from 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?
Given the complexity (5 parameters, 4 required, output schema exists), the description lacks essential context for a creation tool, such as behavior on duplicate names, default values, or required permissions. The presence of an output schema mitigates return value explanation but not the broader completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters described. The description adds no additional meaning beyond the schema, so it meets the baseline expectation but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new database repository for sidecar proxying' clearly states the action and resource. It distinguishes this tool from sibling creation tools like create_database or create_sc_sidecar by specifying 'database repository for sidecar proxying'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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 or constraints. It simply states the action, leaving the agent 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description does not disclose side effects (e.g., idempotency, overwriting), required permissions, or behavior on failure. Output schema exists but description does not clarify return 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?
Single sentence, efficient and front-loaded. Lacks some detail but avoids 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?
Minimal description; missing usage context and behavioral details. Output schema exists but description does not leverage it to reduce burden. Incomplete for a create tool with no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover all parameters (sidecar_id, port, repo_name) with basic details. Description adds no extra semantics beyond schema, so at baseline 3 given 100% 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?
Description clearly states 'Bind a repository to a sidecar listener port,' specifying verb and resource. Differentiates from sibling tools like create_sc_sidecar (creates sidecar) and list_sc_sidecar_bindings/delete_sc_sidecar_binding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select 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 mentioned (e.g., sidecar must exist, port must be unused), and no conditions for successful binding.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits. It only states the action but does not mention side effects (e.g., the request becomes denied, irreversible), permissions required, or any constraints (e.g., the request must be pending). This leaves significant gaps for 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is front-loaded and gets to the point, though it sacrifices some detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (2 params, output schema present), the description is still incomplete. It fails to explain the state change, prerequisites (e.g., request must be pending), or any post-conditions. 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both parameters (request_id UUID, justification reason). The description adds no extra meaning, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Deny') and the resource ('a pending access request'), distinguishing it from siblings like approve_access_request and cancel_access_request. It 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 provided on when to use this tool versus alternatives (e.g., approve or cancel). The description does not mention prerequisites or 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description does not disclose behavioral traits such as side effects, permission requirements, or whether the action is reversible. The one-liner is insufficient for understanding the tool's impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no extraneous words. Every word is essential and the structure is optimal for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence 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 the outcome of approval, potential errors, and lifecycle considerations. It is too minimal for a tool that modifies state.
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?
Both parameters are fully described in the schema (100% coverage). The description adds no additional meaning beyond the schema; it merely restates the tool's purpose. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Approve' and the resource 'pending access request', making the purpose unambiguous. It is distinct from sibling tools like deny_access_request and cancel_access_request.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select 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., deny_access_request). The description does not specify prerequisites like the request must be pending, nor does it indicate when approval 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?
No annotations provided. Description states 'Remove' implying destructive action but lacks details on side effects, reversibility, or impact on existing connections. For a mutation tool, more transparency 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words. However, could benefit from slightly more context 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?
Minimal description for a tool with two parameters and an output schema. Lacks context about prerequisites, effects, or return value. 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?
Input schema has 100% coverage with descriptions for both parameters (sidecar_id, port). Description adds no additional meaning beyond 'remove a listener port', so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Remove' and resource 'listener port from a sidecar', clearly indicating the action. It distinguishes from sibling tools like 'register_sc_sidecar_listener' and 'list_sc_sidecar_listeners'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select 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 'register_sc_sidecar_listener'. No exclusions or prerequisites mentioned. Agent must infer usage from 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?
The description is consistent with the readOnlyHint annotation, but adds no extra behavioral context (e.g., error handling, authentication needs). The annotation already signals it's a safe read 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 concise (8 words, one sentence) with no unnecessary information. While it is brief, it is appropriately sized for a simple get 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?
The tool has an output schema (inferred), so return values need not be described. However, the description does not mention that both parameters are required for a unique instance, which could improve completeness for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The tool description adds no additional meaning beyond the schema, so 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?
The description clearly states the action (Get) and resource (report instance), and distinguishes from sibling tools like list_report_instances. However, it does not explicitly mention the need for both definition_id and instance_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 like list_report_instances or get_report_definition. The description lacks 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 include readOnlyHint=true, and the description ('Get details') aligns with read-only behavior. The description does not add additional behavioral context beyond what annotations provide, but 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 (one sentence) with no fluff. It is concise but could potentially include more detail about the resource or usage 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?
Given the presence of an output schema and clear annotations, the description is minimally sufficient. However, it does not explain that the tool requires both repo_name and username, which are already in the schema, so completeness is adequate but not outstanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for both parameters. The description adds no further meaning to the parameters, so 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?
The description clearly states the action ('Get details') and resource ('service user'). It is specific to a single service user, distinguishing it from sibling tools like 'get_service_users' which lists multiple. However, 'details' is somewhat vague, but overall 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 (e.g., 'get_service_users' for listing all service users). The description does not mention 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description repeats the read-only nature implied by annotations but adds no additional behavioral information (e.g., auth requirements, data freshness). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, clear sentence with no redundant information. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with full schema coverage and an output schema, the description is sufficient. It does not need to explain return values as output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds no extra meaning beyond the schema's parameter descriptions ('Sidecar UUID', 'Instance UUID').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 details for a specific sidecar instance' clearly states the verb 'Get' and the resource 'details for a specific sidecar instance', but does not differentiate from sibling tool 'get_sidecar_instances' which lists instances.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select 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 'get_sidecar_instances' or 'get_sc_sidecar'. 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 provide readOnlyHint=true, so the safe read behavior is clear. The description adds no additional behavioral context (e.g., pagination, result format, or side effects). With annotations, the bar is lower, and the description does not contradict, so a neutral 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, direct sentence without fluff or repetition. Every word is functional. Ideal 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 has 5 parameters including filters and pagination, the description is too minimal. It does not mention that results can be filtered or paginated, nor does it describe the output schema. An agent would benefit from a brief overview of the filtering options.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description does not add any extra meaning beyond the schema definitions. Baseline 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?
The description 'List repo bindings for a sidecar' clearly states the verb (List), resource (repo bindings), and context (for a sidecar). It is specific enough to distinguish from most siblings, though 'list_sc_repo_bindings' is similar in name but not clarified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select 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 'list_sc_repo_bindings' or 'list_sc_sidecars'. No mention of prerequisites 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?
The description correctly indicates the destructive nature (consistent with annotations), but adds no additional behavioral details such as side effects, reversibility, or required permissions. With annotations already setting destructiveHint: true, the description is neutral but not informative 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at 4 words, front-loading the action and resource. However, it could include a bit more context without significantly increasing length, such as noting the requirement for both 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 presence of an output schema and annotations, the description still lacks completeness. It does not explain return values, prerequisites (e.g., the instance must exist), or potential consequences. For a destructive tool, this leaves important gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for both agent_id and instance_id. The tool description does not add any additional meaning or usage context for the parameters, so it meets the baseline without improvement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 instance', making the tool's purpose unambiguous. It distinguishes itself from sibling delete tools like delete_classifier or delete_collection by specifying the resource 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 is provided on when to use this tool versus alternatives (e.g., deactivating instead of deleting), nor are there prerequisites or conditions for usage. The description lacks any context about appropriate 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?
Description adds no behavioral context beyond what annotations already provide (destructiveHint: true). Does not mention what occurs upon deletion, authorization needs, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundancy, efficient conveyance of 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?
With output schema present and simple parameters, the description is minimally adequate but lacks richer context about the operation's implications or error states.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description does not need to explain parameters; the schema already fully defines them. Baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Remove') and resource ('repo binding from a sidecar listener port'), distinguishing it from sibling tools like create_sc_sidecar_binding or list_sc_sidecar_bindings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select 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 delete operations). No prerequisites, side effects, or contextual 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 already indicate destructiveHint=true. The description adds no further behavioral context beyond the annotation, such as irreversibility 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?
Description is a single, front-loaded sentence of 6 words, efficiently conveying the purpose without unnecessary verbosity. However, it could include more detail 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 a destructive operation, the description omits important context such as irreversibility or implications. The presence of an output schema partially mitigates the need for return value explanation, but overall, the description feels incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter 'task_id' described. The description does not add additional meaning beyond the schema, so 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 'Delete telemetry for a specific task' clearly indicates the action (delete) and the resource (telemetry) with scoping (for a specific task), distinguishing it from other delete 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 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 get_task_telemetry or other deletion tools. No exclusions, 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?
The annotations indicate readOnlyHint: true, which matches the 'Get details' description. However, the description adds no further behavioral context (e.g., authentication requirements, data freshness, or error scenarios). The annotation already covers the safety profile, so a baseline score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is front-loaded with the core purpose and effectively communicates the tool's function without extra 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 simplicity of the tool (one required parameter, readOnlyHint, and an output schema), the minimal description is adequate. However, it could briefly mention that the tool returns full details of the specified repository, which 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 input schema already documents 'repo_name' with a clear description ('Repository name.'), achieving 100% coverage. The tool description does not add any additional meaning or constraints beyond what the schema provides, so a score of 3 is justified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 details for a specific repository,' which identifies the action (get) and resource (repository). While it distinguishes from list_sc_repos implicitly, it does not explicitly differentiate from other repository-related tools like update_sc_repo or delete_sc_repo, which is acceptable given the 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. The agent must infer that this tool is for fetching details of a single repository, but there is no explicit mention of use cases or exclusions, such as to not use it for listing or modifying.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description fails to disclose any behavioral traits such as destructiveness, reversibility, permission requirements, or effects on the collection or classifiers.
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 a single sentence that is front-loaded and to the point, containing 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?
Input schema and output schema exist, covering parameter and return value details. However, the description lacks behavioral context for the removal operation, making it minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing adequate parameter descriptions. The description adds no additional meaning beyond the schema, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 verb 'remove' and the resource 'classifiers from a collection', accurately reflecting the tool's function and distinguishing it from the sibling 'add_classifiers_to_collection'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select 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 remove vs. other modification tools). No exclusions or prerequisites 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?
No annotations provided, so description carries full burden. It says 'currently pinned comment' implying uniqueness, but comment_id parameter suggests specification. No disclosure of idempotency, error conditions, or side effects (e.g., what happens if comment not pinned). 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no unnecessary words. Effectively 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?
Tool has 3 required parameters and an output schema, but the description does not explain the response or consequences (e.g., what state the report is in after unpin). Adequate but not comprehensive given the operation's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already provides 100% description coverage for all three parameters (definition_id, instance_id, comment_id). The tool description does not add additional meaning beyond the schema. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (unpin) and resource (comment on report instance). It distinguishes from sibling tool 'pin_report_comment' and is specific about 'currently pinned 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 versus alternatives (e.g., pin_report_comment). No prerequisites, conditions, or exclusions mentioned. The description does not help the agent decide 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 annotation readOnlyHint: true already conveys the read-only nature. The description does not add further behavioral detail (e.g., required permissions, return content). Since the annotation carries the burden, a score of 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 a single concise sentence with no extraneous information. It is front-loaded and efficient, though it could be slightly expanded for completeness.
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, an output schema exists, and annotations are present, the description is minimally complete. However, it does not explain what 'details' entail or how this tool relates to repo user management, leaving some context implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents both parameters ('Repository name.' and 'Database username.'). The description adds no additional meaning beyond the schema, resulting in a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get details') and the resource ('a specific repo user'). It distinguishes itself from sibling tools like list_sc_repo_users (which lists multiple) and update_sc_repo_user (which modifies), making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_sc_repo or list_sc_repo_users. There is no mention of context or scenarios that would make this tool 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 aligns with the readOnlyHint annotation, but adds no additional behavioral context beyond what the annotation already provides. The description is consistent and non-contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. It is front-loaded and 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?
With an output schema present and a simple single-parameter tool, the description is largely sufficient. However, it could briefly mention what 'details' entail (e.g., configuration, status) to 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?
Schema coverage is 100% and the parameter description ('Sidecar UUID.') is clear. The description adds no further meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 'details for a specific sidecar,' which is appropriate. However, it does not differentiate from sibling tools like 'list_sc_sidecars' or 'get_sc_sidecar_binding,' missing an opportunity to clarify 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. Given the large number of sibling tools, a hint about using it when you have a specific sidecar ID would be helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X 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`, signaling safe read operation. The description adds context about agent types but does not reveal additional behaviors like pagination details or data sorting. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. It is front-loaded and 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 list tool with a complete input schema and an output schema (present but not shown), the description is mostly sufficient. It could mention pagination behavior explicitly, but the parameter descriptions cover that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well-documented. The description only echoes the agent type filter, adding little new 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 specifies the tool lists ALTR agents (SIS or CLASSIFIER) in the organization. However, it does not differentiate from sibling tools like `get_sc_agent` (singular) or other list tools, so it doesn't earn a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., when to use `get_sc_agent` instead). It only states the scope 'in your organization', which is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "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 readOnlyHint annotation already indicates a read operation. The description adds scope but lacks details on pagination, ordering, or filtering behavior beyond what the schema provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no wasted words. It is appropriately sized for a simple list operation.
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 low-complexity list tool with an existing output schema and annotations, the description is adequate. It might benefit from mentioning that it lists all sidecars or that pagination is supported, but is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both parameters (limit and contiguous_id). The description adds no additional parameter meaning beyond the schema, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'List' and the resource 'sidecars' with scope 'in your organization', differentiating it from sibling list tools like list_sc_sidecar_bindings by 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 explicit guidance on when to use this tool versus alternatives such as get_sc_sidecar or list_sc_sidecar_bindings. The description does not provide any 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?
No annotations are provided, so the description carries the full burden. It discloses that the request requires approval before access is granted (behavioral trait). However, it lacks details on side effects, idempotency, or required permissions. Given the absence of annotations, this is adequate but not exhaustive.
Agents need to know what a tool does to the world before 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 reasonably concise, with the main purpose stated first, followed by a usage hint and structured parameter explanation. Every sentence adds value, though the rules explanation could be slightly more compact. Overall, it is well-organized 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?
The tool has 7 parameters (4 required) and an output schema. The description covers the core workflow and the complex rules parameter, but it could mention the relationship with other access request tools (e.g., approve, cancel) to provide better context. It is functionally complete for basic use but lacks some contextual depth.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining the structure of the 'rules' parameter with actors, objects, and access fields, which goes beyond the schema's generic description. Other parameters are well-described in schema. This extra detail justifies a 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 it creates a new access request for data access approval, which is specific and action-oriented. However, among many 'create_*' sibling tools, it doesn't explicitly distinguish itself from others like create_database, but the context of access approval provides some differentiation.
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?
It gives a pointer to use get_access_requests to check status after creation, which is helpful. But it does not specify when to use this tool versus related tools like approve_access_request, cancel_access_request, or deny_access_request. Usage context 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description must carry behavioral burden. It only repeats schema constraints on name/namespace but does not disclose side effects, duplicate handling, or permissions required for creation.
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, front-loaded sentences. No extraneous 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?
While an output schema exists, the description lacks context on prerequisites, error cases, or when to use this over sibling tools. Minimal completeness for a key-creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and descriptions already provided. The tool description adds no new meaning beyond what the schema states regarding namespace and name 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 it creates a new FPE encryption key, specifying the resource (key) and action (create). It is distinct from sibling tools like create_tweak or deactivate_key.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., create_tweak or rotate_key). The context of encryption key creation is implied but not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It mentions recording approval and enabling pinning, but does not reveal whether multiple sign-offs are allowed, if sign-offs can be undone, required permissions, or error scenarios. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loading the main purpose with no extraneous information. It is efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (so return values are covered) and full parameter schema, the description provides a basic overview and a post-condition. However, it lacks important behavioral context such as idempotency, permissions, and error handling, making it adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what the schema already provides for each parameter. It does not explain the relationship between action, attestation, and comments.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 signs off/reports approval on a report instance, using specific verbs ('Sign off', 'Records approval') and resource ('report instance'). It distinguishes from sibling tools like create_report_comment (creates comments) and pin_report_comment (pins after sign-off).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a sequence (sign off before pinning comments) but does not explicitly state when to use this tool vs alternatives like list_report_sign_offs or get_report_sign_off. It lacks explicit when-to-use or 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 declare readOnlyHint=true, so the description need not repeat it. However, the description adds no behavioral context beyond that (e.g., pagination behavior, response structure). It is adequate but does not enhance 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 a single, concise sentence that states the tool's purpose without wasted words. It could be improved by front-loading key details (e.g., pagination) but remains 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 straightforward list operation with a documented schema and an output schema, the description sufficiently covers the tool's functionality. It might omit pagination hints, but overall completeness is high.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already documented. The tool description does not add semantic value beyond the schema, earning a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb (list), resource (users), and scope (for a repository). It clearly distinguishes from sibling tools like create_sc_repo_user or get_sc_repo_user, 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 on when to use this tool vs alternatives like get_sc_repo_user (single user) or list_sc_repos. No mention of pagination or read-only nature, though annotations cover readOnlyHint. Usage context 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so full burden falls on description. It only states 'Restore' without disclosing side effects, required permissions, or state changes beyond the obvious. No mention of what happens to the definition's archive status 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the key action and object. 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?
The tool is simple with one parameter, but the description lacks context about prerequisites (e.g., definition must be in archived state) or what the output signifies. While an output schema exists, the description does not elaborate on return values or effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description adds no additional meaning to the single parameter 'definition_id' beyond what the schema already provides. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Restore' and the specific resource 'archived audit report definition'. It differentiates from sibling 'archive_report_definition' by being the inverse 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 implies usage as the counterpart to archiving, but provides no explicit guidance on when to use or alternatives. No context for prerequisites or exclusions 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?
No annotations are present, so the description must disclose behavioral traits. It only states partial update behavior but omits critical details such as authorization needs, error handling (e.g., if agent_id does not exist), and side effects. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences with no wasted words. It is front-loaded with the primary action and immediately clarifies the partial update behavior, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters (1 required) and an output schema, the description is minimally adequate. It covers the core update purpose but lacks context about identification (agent_id role), return values (though schema exists), and when partial vs full update applies. There is room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by clarifying that only provided fields are changed, which explains the semantics of nullable parameters (default null means unchanged). This goes beyond the schema's explicit 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 'Update an existing agent,' which is a specific verb+resource combination. It distinguishes from sibling tools like create_sc_agent and delete_sc_agent, and the phrase 'Only provided fields are changed' further clarifies the partial update behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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 create_sc_agent or other update tools. There is no mention of prerequisites, context, 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosure. It only states the action without revealing side effects, required permissions, or what happens to old credentials.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. It is appropriately concise for a simple update 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?
The tool has an output schema, so return values are not required in the description. However, it lacks context on prerequisites (e.g., user must exist) and idempotency. Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds no extra meaning beyond what the schema provides, resulting in a baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the specific resource ('a repo user's credential reference'), distinguishing it from sibling tools like create_sc_repo_user, delete_sc_repo_user, get_sc_repo_user, and list_sc_repo_users.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives (e.g., creating or deleting a repo user). The purpose is implied but not clarified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X 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. Description describes return data but adds no extra 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?
Two concise sentences front-loading purpose 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?
Adequately describes purpose and return data. With output schema present, completeness is sufficient. Could briefly explain pagination, 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?
Schema description coverage is 100% with clear descriptions for each parameter. Description does not add 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?
Description clearly states it gets task telemetry for a specific agent, specifying the resource and verb. Distinguishes from siblings like get_task_telemetry by adding 'for a specific 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 versus alternatives like get_task_telemetry. No context on 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?
The description lacks behavioral details beyond what the annotation (readOnlyHint: true) already provides. It does not describe pagination behavior, return format, or any side effects, though the safety profile is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and contains no unnecessary words. Every word is essential.
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 an output schema exists (presumably covering return values), the description is adequate for a straightforward list operation. It does not explain domain concepts like sidecar, but those are likely assumed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all parameters (sidecar_id, limit, contiguous_id). The tool description adds 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 verb 'list' and the resource 'running instances for a specific sidecar.' It distinguishes itself from sibling tools like 'get_sidecar_instance' (singular) and 'list_sc_sidecars' (lists sidecars, not instances).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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 that for a single instance one should use 'get_sidecar_instance' or specify 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 declare readOnlyHint=true, which is consistent with 'list'. The description adds no extra behavioral context (e.g., required permissions, side effects). Since annotations cover the read-only nature, the description doesn't need to duplicate, but it also doesn't add value 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words. It is front-loaded and 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 list tool with full schema coverage and an output schema, the description is adequate. It covers the essential purpose. While it could mention pagination or that agent_id is required, the schema already provides that detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all 3 parameters (agent_id, limit, contiguous_id). The description adds no parameter-specific information, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List tasks assigned to an agent.' uses a specific verb ('list') and resource ('tasks') with a clear scope ('assigned to an agent'). It distinguishes from sibling tools like get_sc_agent_task (single) and get_agent_task_telemetry (telemetry).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps 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., get_sc_agent_task for a single task). No exclusions 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds scope context ('configured for sidecar proxying') but does not disclose pagination behavior, default limits, or that all repos are returned without filters. Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 8 words, no redundancy. Efficiently conveys core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description is sufficient given output schema existence (return values documented there). Could mention default behavior (lists all if no filters) for completeness, but adequate 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 100%, so the schema fully documents all three parameters. Description adds 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?
Description clearly states the verb (List), resource (database repositories), and context (configured for sidecar proxying). Distinct from siblings like get_sc_repo (single) and create_sc_repo (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 on when to use this tool vs alternatives like list_sc_repo_bindings or get_sc_repo. Sibling list includes many similar list tools, but no differentiation 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, so the description doesn't need to state safety. The description adds the filter option but doesn't disclose pagination, default limits, or the constraint that username_starts_with only works with repo_name. These are in the schema, but the description could add 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 a single short sentence, front-loading the core purpose. Every word is meaningful, though it could be expanded slightly to include key behavioral 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 the presence of an output schema (handling return values) and 100% schema coverage for parameters, the description covers the basic purpose but omits pagination and filter constraints that impact usage. 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description adds no extra meaning beyond 'Optionally filter by repo', which maps to the repo_name parameter already described in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and resource ('service users'), with an optional filter ('by repo'). This distinguishes it from sibling tools like 'get_sc_service_user' (single user) and 'create_sc_service_user' (creation).
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 multiple users and optionally filtering by repo, but provides no explicit guidance on when to use this tool versus alternatives (e.g., 'get_sc_service_user'), nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. The description only states creation and that classifiers can be added to collections and used in jobs. It does not mention side effects, idempotency, error handling, or what happens on duplicate names. This is insufficient for a creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first sentence states the core action and resource, second provides usage context. Extremely concise with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 required parameters, an output schema, and no annotations, the description is brief but covers the core purpose and usage scenario. However, it lacks behavioral and lifecycle details that would help an agent use it correctly. Output schema exists but description doesn't mention it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter already described in the input schema. The description adds no specific parameter details beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a custom data classifier for specific patterns, and distinguishes from built-in classifiers by mentioning when to use (when built-in don't cover data types). It also mentions that custom classifiers can be added to collections and used in jobs, which adds context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when ALTR's built-in classifiers don't cover your data types,' providing clear when-to-use guidance. However, it does not specify when not to use or mention alternatives beyond built-in classifiers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X 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, indicating a safe read operation. The description adds no additional behavioral details (e.g., pagination, filtering 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?
Description is a single concise sentence that conveys the purpose effectively. It is front-loaded but 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.
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 full parameter documentation, the description covers the basic purpose. However, it omits hints about pagination (e.g., using exclusive_start_key), which would improve completeness for a 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 coverage is 100%, so parameters are well-documented in the schema. The description adds no extra meaning or usage guidance for the parameters, earning a baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'List access requests in your ALTR organization' with a specific verb (list) and resource (access requests), and distinguishes from siblings like get_access_request (singular) and approve_access_request.
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 no guidance on when to use this tool versus alternatives like get_access_request or other filter methods. It merely states the 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?
The description aligns with the 'readOnlyHint' annotation by indicating a read operation ('Get details'). However, it adds no additional behavioral context beyond what the annotation already provides, such as rate limits 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 a single, clear sentence that efficiently conveys the tool's purpose with no 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's simplicity and the presence of an output schema (which handles return value documentation), the description provides sufficient information for an AI agent to understand the tool's function.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters ('agent_id' and 'instance_id'). The tool description does not add any meaning beyond the schema, meeting the baseline expected.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 specifies the action 'Get details' and the target resource 'specific agent instance'. It effectively distinguishes from sibling tools like 'get_agent_instances' (plural) and similar getters for 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating what it does, but provides no explicit guidance on when to prefer this tool over alternatives (e.g., 'get_agent_instances' for listing). 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It only specifies that the tool controls a running job and status options, but does not mention prerequisites, side effects, or what happens if the job is not in a valid state (e.g., already completed).
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. The most critical information is front-loaded (verb, resource, actions). Every sentence 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?
Description covers core function and parameters, but with no annotations, it lacks details on expected behavior (e.g., whether it returns the updated job, error handling, or permission requirements). Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions. The description adds the same status options as the schema, no new semantic depth. Baseline of 3 is appropriate for full 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 action (control) and resource (running classification job) and lists specific status transitions (pause, cancel, resume), distinguishing it from sibling tools like create_job or get_jobs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use for managing long-running classification jobs and lists allowed statuses, providing clear context. Lacks explicit 'when not to use' but is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It states 'Only provided fields are changed', conveying a partial update (patch) behavior, which is helpful. However, it omits details like required permissions, potential side effects, or whether the operation is destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with just two sentences, both front-loaded. Every word is necessary and 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 tool's simplicity (5 parameters, 2 required) and the presence of an output schema (not shown), the description is adequate for basic understanding. However, it lacks context on identification (repo_name and username likely form a composite key) and any potential impacts of updating sensitive fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description goes beyond by clarifying that only provided fields are updated, which explains the semantics of optional parameters (they are only changed if included). This adds meaningful context beyond the schema's field 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 'Update a service user' with a specific verb and resource. It effectively distinguishes this tool from sibling tools like create_sc_service_user, get_sc_service_user, and delete_sc_service_user, which have 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?
The description provides no guidance on when to use this tool versus alternatives (e.g., create_sc_service_user for new users, or other update tools). It does not specify prerequisites or scenarios where update should be avoided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses partial update behavior, but lacks details on side effects, permissions, error handling, or outputs. Since no annotations exist, the description carries full burden and is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, focused sentences with no superfluous content. Front-loaded action verb and resource.
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 tool with full parameter descriptions and an output schema, but could benefit from mentioning that sidecar_id is required and that other fields are optional. Given sibling tools, it lacks uniqueness context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. The description adds 'Only provided fields are changed' which clarifies partial update semantics, but does not add meaning beyond schema for individual 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 it updates a sidecar, distinguishing from create and delete siblings. The verb 'Update' combined with 'sidecar' uniquely identifies 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for updating a sidecar with partial updates via 'Only provided fields are changed', but no explicit guidance on when to prefer this over other update tools (e.g., update_sc_agent) or any 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?
No annotations are provided, so the description carries the full burden. It does not disclose behavioral traits such as side effects, required permissions, or whether the operation is destructive. The description focuses on rule structure but omits 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 concise, with a clear purpose sentence followed by a structured bullet list for the rules parameter. It is front-loaded and well-organized, though it could be slightly more compact without losing clarity.
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 complexity (7 params, 6 required, no output schema described but exists), the description covers the core purpose and rules structure well. However, it lacks information about return values, error conditions, or prerequisites. Since output schema exists, return value explanation is not required, but the description could still mention that it returns the created policy.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds significant value by detailing the exact structure of the 'rules' parameter—specifying required fields (type, actors, objects) with subfield types and constraints (e.g., 'condition': 'equals'). This clarifies what would otherwise be vague 'List of OLTP access rule objects' 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 states 'Create an access management policy for an OLTP datasource,' providing a specific verb ('Create'), resource ('access management policy'), and context ('OLTP datasource'). This clearly distinguishes it from sibling tools like 'create_policy' (general) and 'create_snowflake_access_policy' (Snowflake-specific).
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 OLTP datasources but does not explicitly state when to use this tool versus alternatives (e.g., 'create_policy', 'create_snowflake_access_policy'). There is no guidance on prerequisites 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?
No annotations are provided, so the description must carry full behavioral disclosure. It mentions the naming constraint and that it generates a random value, but does not specify side effects, idempotency, failure modes, or permission requirements. Minimal behavioral context beyond the core operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two sentences) and front-loaded with the core action. Every sentence adds necessary information, no redundancy or 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's simplicity (one parameter, no annotations, output schema exists), the description covers the essential purpose and naming constraint. It could mention error handling for duplicate names or clarify the return value, but the presence of an output schema mitigates that need.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter is already well-documented. The description adds context that the tweak is for FPE, which clarifies the parameter's role, but mostly repeats the schema's constraint about leading/trailing spaces. 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 it creates a new FPE tweak, explaining it generates a named random value for format-preserving encryption. It distinguishes from sibling tools like create_key by specifying the FPE context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the name and description, but there is no explicit guidance on when to use this tool versus alternatives (e.g., create_key) or exclusions. The description lacks when-not-to-use 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 destructiveHint=true. The description adds a precondition (no users/bindings) that affects behavior, but does not disclose what happens if the precondition fails, whether deletion is reversible, or any other side effects. It 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?
Two short sentences with no filler. The action and key constraint are front-loaded. Every word is necessary and earned.
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 single-parameter deletion tool with annotations and an output schema (implied), the description is adequate. It covers the action and a critical precondition. Could mention permanence of deletion or that the repo must exist, but not strictly 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?
Schema coverage is 100% (one parameter with description 'Repository name.'). The description does not add any additional meaning or constraints about the parameter 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 the action (Delete) and the resource (repository), and adds a key precondition (no users or bindings), which distinguishes it from related sibling tools like create_sc_repo or update_sc_repo.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a precondition (must have no users or bindings) but does not explicitly guide when to use this tool versus alternatives like delete_sc_repo_user or list_sc_repo_bindings. There is no mention of when not to use it or steps to prepare the repository 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?
The readOnlyHint annotation already indicates the tool is read-only; the description adds no additional behavioral context such as error handling or authorization requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of six words with no extraneous information; perfectly concise and 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 retrieval tool with fully described parameters and an output schema, the description is sufficient to understand its purpose, though it lacks usage 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?
Input schema provides 100% coverage with descriptive parameter names and descriptions; the description adds no extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'Get' and explicitly states the resource 'sidecar-repo binding', clearly distinguishing it from list tools like 'list_sc_sidecar_bindings'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives; the tool name and the presence of list siblings imply it is for fetching a single binding, but this is 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?
The description confirms read-only behavior ('Get'), consistent with the 'readOnlyHint' annotation. However, it adds no additional behavioral context beyond what the annotation already provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, perfectly front-loaded, and no extraneous information. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return values are documented externally. The description is sufficient for a simple single-parameter getter, though it could mention telemetry type or format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes 'task_id' as 'Task UUID.' with 100% coverage. The description adds no further meaning 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 description clearly states the verb 'Get', the resource 'telemetry for a specific task', and the identifier 'by its ID'. It distinguishes from sibling tools like 'delete_task_telemetry' and 'get_agent_task_telemetry' 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The purpose is clear from the name, but the description lacks context on prerequisites or when to prefer other telemetry 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 'returns sign-offs from all users', which is useful context. Annotations already provide readOnlyHint: true, so no contradiction. However, pagination behavior (limit/cursor) is not mentioned.
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 the action, second clarifies return content. No unnecessary words, 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?
An output schema exists, so return format is covered. The description explains the core behavior adequately. Could mention pagination support given limit/cursor parameters, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes all parameters. The description adds no extra detail beyond the overall purpose, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all sign-offs for a report instance', specifying the verb (list), resource (sign-offs), and context (report instance). The sibling tools include 'create_report_sign_off' and 'get_report_sign_off', so 'list' is distinct and appropriate.
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 retrieving all sign-offs but does not explicitly state when to use this tool versus alternatives like 'get_report_sign_off'. No guidance on pagination 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?
With no annotations provided, the description carries full burden for behavioral disclosure. It only states that the check runs immediately, but does not explain side effects, authentication requirements, rate limits, or whether the operation is synchronous or asynchronous.
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. Every word adds value, with no redundant or vague language.
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 complexity of sibling tools and the presence of an output schema, the description effectively communicates the core purpose and immediate execution. It could be improved by briefly noting prerequisites (e.g., policy existence) or mentioning that the output schema provides result details, but it remains sufficiently complete for a simple single-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the policy_id parameter with a note not to URL-encode (100% coverage). The description adds no new parameter information, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool triggers a manual compliance check for a grant/access policy, using a specific verb and resource. It distinguishes from siblings like create_policy and get_policies by specifying the immediate execution aspect.
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 using this tool when an immediate policy check is needed instead of waiting for a scheduled run. While it doesn't explicitly list alternatives or exclusions, the context is clear and no other sibling appears to offer the same immediate check.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses partial update behavior and notes that configuration rules vary by database type, but lacks details on permissions, side effects, or reversibility. The reference to create_sc_agent_task delegates some 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 very concise: two sentences that efficiently state the purpose, partial update nature, and a note about configuration rules. 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?
Given the schema covers all parameters and an output schema exists, the description is mostly complete for an update tool. It delegates configuration rule details to create_sc_agent_task, which is acceptable, but could include a brief note about the output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds that only provided fields change, which clarifies update semantics, but does not provide additional meaning beyond the schema descriptions for individual 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 'Update an agent task' with a specific verb and resource. It also mentions 'Only provided fields change,' which clarifies the partial update nature, and distinguishes it from sibling tools like create_sc_agent_task.
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 implicitly indicates usage for updates via the verb 'Update', and references create_sc_agent_task for details, but does not explicitly state when to use this tool versus alternatives (e.g., create or delete). Without explicit when-not or alternative guidance, it scores a 3.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers token format, storage for detokenization, deterministic vs. random, rate limits (492/month, 50/sec), max values (4096), and max character length (1024). It does not cover error behavior or authentication needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with five sentences, front-loading the action and including all necessary details without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and that an output schema exists, the description adequately covers tokenization process, constraints, and rate limits. It lacks details on error handling but is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so schema already describes parameters. The description adds marginal value by explaining deterministic behavior ('same token for same input'), but for 'values' it mostly repeats the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool tokenizes plaintext into vault tokens, specifying the token format and storage. However, it does not differentiate from sibling 'critical_tokenize', leaving ambiguity about when to use which.
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 tokenization but gives no explicit guidance on when to prefer this tool over siblings like 'critical_tokenize' or 'vault_detokenize'. No prerequisites or when-not 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?
No annotations are provided, so the description must fully disclose behavior. It only states the creation action and the mutual exclusivity constraint, but lacks information on permissions, side effects, error conditions, or the return value (though output schema exists). This is insufficient for safe invocation.
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, and a clear constraint. No redundant or unnecessary information. Very 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 description does not explain prerequisites (e.g., repository must exist), the purpose of the service user, or the format of the credential parameters. Although an output schema exists, the description lacks context for complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds critical semantic nuance: the mutual exclusivity of 'aws_secrets_manager' and 'azure_key_vault' parameters, which is not enforced by the schema. This adds value beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'create' and the resource 'service user for a repository', distinguishing it from sibling tools like 'delete_sc_service_user' or 'create_sc_repo_user'. The additional constraint about providing exactly one credential type adds specificity.
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 explicitly says 'Provide exactly one of aws_secrets_manager or azure_key_vault', which is a crucial usage constraint. However, it does not compare to alternatives like 'create_sc_repo_user' or explain when a service user 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?
No annotations are provided, so the description carries the full burden. It details the rule structure but omits behavioral aspects like immediate enforcement, permissions required, or whether creation overrides existing policies. Basic context is given 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 well-structured with a clear first sentence and detailed bullet points for rules. It is not overly verbose, though some redundancy exists (e.g., repeating 'list of dicts' pattern could be more concise).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists and parameters have 100% coverage, the description covers the essential purpose and the complex rule structure. It lacks details on error cases or output format, but the presence of an output schema mitigates 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?
Schema coverage is 100%, providing a baseline of 3. The description adds significant value for the complex 'rules' parameter by specifying required fields (actors, objects, access, tagged_objects) and their subtypes, which is beyond the schema's generic 'list of objects' definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 Snowflake access policy and specifies its components (roles, objects, access). It distinguishes itself from siblings like create_oltp_access_policy and update_snowflake_access_policy by targeting Snowflake datasources.
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 explains what the policy does (enforced by ALTR, scheduled checks) but does not explicitly compare to alternatives like create_oltp_access_policy or update_snowflake_access_policy. It lacks guidance on when to use this tool vs others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X 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. Description adds no further behavioral context beyond the verb 'Get', which aligns with annotation. No additional disclosure of behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb and object, no unnecessary words. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter, output schema present, and annotations provided, the description is complete enough to understand what the tool does and what input is 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?
Schema covers 100% of the parameter with description 'ID of the report definition.' Description adds no extra meaning beyond repeating the resource type. Baseline 3 as schema does the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 'Get' and resource 'single audit report definition by ID,' distinguishing from siblings like list_report_definitions and create_report_definition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives (e.g., list_report_definitions). Implied by the verb and resource, but no when-not or alternative mentions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X 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 the description does not add behavioral details beyond that. No mention of authentication, rate limits, or return format, but the read-only nature is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple list operation, presence of output schema, and full parameter descriptions, the description is sufficient. No gaps in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds no extra meaning beyond the schema definitions. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (List) and resource (listener ports) and scope (on a sidecar), distinguishing it from sibling tools like list_sc_sidecars or get_sc_sidecar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives (e.g., get_sc_sidecar or register/deregister listeners). The context is only implied by the 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?
No annotations are provided, so the description carries full burden. It discloses async behavior, uuid expiry (30 days), and AND logic for filters. It does not mention if the operation is read-only or other side effects, but it is sufficient for basic understanding.
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, front-loading the purpose and adding necessary workflow details in just three sentences with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 17 parameters and an output schema, the description explains the async pattern and filter logic. However, it does not differentiate this tool from the similarly named sibling search_query_audits, which could cause confusion.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes each parameter well. The description only adds that filters use AND logic, which adds minimal value 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 it searches sidecar query audits with filters. It specifies the async nature and the use of get_audit_results to retrieve results, distinguishing it from siblings like get_audit_results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly explains the async workflow and the need to use get_audit_results later. It does not explicitly mention when not to use it versus search_query_audits or search_system_audits, but the context of 'sidecar query audits' provides some 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?
No annotations are provided, so the description carries full burden. It only mentions update semantics but omits behavioral traits like authorization requirements, idempotency, or side effects (e.g., impacting existing connections). This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero wasted words. The purpose is front-loaded, and the partial update behavior is immediately explained. Highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given high parameter count (14) and no annotations, the description is minimal. It does not mention prerequisites (e.g., database_id must exist) or return values (though output schema exists). While it covers the core action, more context would improve agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with detailed parameter descriptions. The description adds the important nuance that omitted fields remain unchanged, which goes beyond the schema. This compensates for the lack of per-parameter semantic depth.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the verb ('Update') and the resource ('a database connection's properties'). Among siblings like create_database and delete_database, it is unambiguous as an 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Only the fields you provide will be updated; omitted fields remain unchanged', which clarifies the partial update behavior. However, it does not explicitly exclude alternatives like create_database or delete_database for when to use this tool versus 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?
With no annotations provided, the description bears full responsibility for disclosing behavioral traits. It states it creates a new definition but does not mention whether it is idempotent, what happens if a definition with the same name exists, authentication requirements, or any side effects. This lack of detail leaves the agent uninformed about important behavioral boundaries.
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 plus a header. The first sentence states the primary purpose, and the second adds immediate next-step guidance. Every word earns its place with zero 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 tool's complexity (10 parameters) and the presence of an output schema (not shown), the description covers the main creation intent and workflow linkage. It could mention that the tool returns the created definition object, but since output schema exists, it is not strictly required. Overall, it provides sufficient context for an agent to understand and correctly invoke the 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 100% description coverage, so the baseline is 3. The description adds value by providing a high-level overview of what the parameters collectively achieve and includes extensive, practical examples for the 'schedule_cron' parameter (e.g., common cron patterns) and clear shapes for 'delivery' and 'filters'. This goes beyond the schema's individual descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('new audit report definition'), with a verb+resource structure. It also distinguishes from sibling tool 'trigger_report_definition' by mentioning the explicit next step, 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on the typical workflow by stating 'After creating, use trigger_report_definition to generate a report on demand.' This implies when to use this tool and suggests an alternative for report generation. However, it does not explicitly mention when not to use it or contrast with other creation tools in the sibling list.
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?
Discloses token format (token_XXXX..., 64+ chars), detokenization ability, deterministic vs random option, and size limits. No contradictions with annotations (none 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?
Well-structured with clear sections, front-loading the main action. Each sentence adds value, no redundancy. Concise yet complete.
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 annotations but high schema coverage and presence of output schema, the description sufficiently covers behavior, constraints, and parameters. All necessary context for correct invocation is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters (values, deterministic) with descriptions. Description adds context: token format, deterministic behavior effect, and 128 code units limit per value, enhancing understanding beyond 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?
Description clearly states it tokenizes plaintext using ALTR critical tokenization, with format and behavioral details. It distinguishes from siblings like vault_tokenize by specifying 'critical tokenization', though not explicitly contrasting.
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 constraints (max 1024 values, 128 UTF-8 code units per value) and mentions detokenization capability. Does not explicitly state when to use this tool vs alternatives like vault_tokenize or critical_detokenize.
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 set destructiveHint=true, and the description adds valuable context by clarifying that the removal is permanent and does not affect the actual database. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, using two short sentences. The first sentence states the action, and the second clarifies the permanence and scope. No unnecessary words 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 output schema exists, the description does not need to explain return values. It covers the key nuance of not affecting the actual database. However, it could mention prerequisites like permissions or required database state. Still, it's fairly complete for a delete tool with annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters. The description does not add additional parameter meaning. Baseline 3 is appropriate as the description adds no extra semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool disconnects and removes a database from ALTR, emphasizing it only affects the ALTR connection, not the actual database. This distinguishes it from sibling tools like create_database or update_database.
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 or not use this tool, nor does it compare it to alternatives like delete_collection or delete_agent_instance. It implicitly guides by clarifying the scope, but 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide destructiveHint=true, but the description adds atomicity and mentions decrementing agent and service user task counts. This goes beyond annotations, offering operational insight.
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 adds behavioral details. No wasted words, front-loaded with key 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?
With output schema present, description need not explain return values. It covers operation, atomicity, and side effects. Could mention error handling but complete enough for a simple delete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions of agent_id and task_id as UUIDs. The description does not add additional parameter semantics, meeting the baseline but not exceeding 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 'Delete an agent task' with specific verb and resource. It distinguishes from sibling tools like delete_sc_agent and update_sc_agent_task by specifying the exact resource and adding atomicity and count decrement details.
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 when to use or alternatives. While deletion is straightforward, no guidance on conditions or when not to use limits the score. It 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, and the description adds that it returns a pre-signed URL, which is behavioral context beyond the annotation. No side effects disclosed, but consistent with read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no redundancy. Every word is useful and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is sufficient for a simple retrieval tool with an output schema present. It lacks mention of permission requirements or the need for the report instance to be generated, but these are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with descriptions (definition_id, instance_id, format with default and valid values). The tool description adds no extra meaning beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Get a download URL for a report instance.' It specifies the resource (download URL) and return value (pre-signed URL). This distinguishes it from sibling tools like get_report_instance or list_report_instances.
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 downloading a report file, but does not explicitly state when to use this over alternatives (e.g., get_report_instance for metadata, list_report_instances for listing). No guidance on prerequisites 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 mark it as read-only. The description adds transparency by noting that null/empty is returned if not signed off, which is helpful 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 that convey the entire purpose and behavior with no unnecessary words. Front-loaded with the main 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 the presence of an output schema and annotations, the description adequately covers the tool's behavior. It mentions the null return case, which is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds no additional meaning for parameters. It meets the baseline but does not compensate further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 retrieves the current user's sign-off for a report instance, using a specific verb and resource. It distinguishes from sibling tools like 'create_report_sign_off' and 'list_report_sign_offs' by focusing on the current user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for personal sign-off checking by mentioning 'current user', but does not explicitly state when to use it over alternatives like list_report_sign_offs. No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations (readOnlyHint=true) already indicate no destructive behavior. The description adds transparency by listing the masking level codes and their meanings, which is useful beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with two paragraphs: the first explains the tool's purpose, the second lists masking level references in a clear, structured format. No unnecessary words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with one parameter and an output schema (implied), the description covers essential aspects: what the rules show, the meaning of masking levels. It lacks mention of pagination or ordering, but given the single parameter and 'view all' nature, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides a clear description for the only parameter (policy_id), with instructions on usage and encoding. Schema coverage is 100%, so the description does not need to add much; it provides no additional parameter details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action ('View all masking rules configured for a specific policy') and the resource ('masking rules for a policy'), with additional detail on what it shows (roles, masking levels, tag values). It clearly distinguishes from sibling tools like add_rules, delete_rule, update_rule.
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 implies usage by requiring a policy_id but lacks 'when not to use' or alternative suggestions, such as when to use add_rules or update_rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "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 context about returning the current or historical version, but given the annotation 'readOnlyHint: true' already indicates a safe read operation, the description offers minimal additional behavioral transparency. No mention of error handling or permissions.
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 convey the purpose and key behavior with no redundancy or extraneous information. 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?
For a simple read-only retrieval tool with an output schema present, the description covers the essential behavior (current vs. historical version). It is sufficiently complete, though it lacks mention of possible error conditions or prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already has 100% description coverage, including 'Omit to get the latest' for the 'sequence' parameter. The description repeats this information without adding new semantic details 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 explicitly states 'Get a single FPE tweak by name,' providing a specific verb and resource. It distinguishes from siblings like 'list_tweaks' by focusing on a single tweak, and mentions returning current or historical versions.
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 explains when to use the optional 'sequence' parameter to retrieve historical versions versus omitting it for the latest. However, it does not provide explicit when-not-to-use guidance or contrast with direct alternatives like 'list_tweaks'.
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, and the description adds ordering behavior (pinned first, chronological), which is consistent. No further behavioral details are needed given the simplicity.
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, with the purpose stated upfront and ordering detail in the second sentence. 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 tool is a simple list operation with pagination and an output schema exists, the description provides sufficient context. It could mention that it returns a list of comments, but that is likely covered by the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are well documented in the schema. The tool description does not add any additional meaning to the parameters 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 it lists comments on a report instance and specifies the ordering (pinned first, then chronological). This distinguishes it from sibling tools like create_report_comment, pin_report_comment, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage but does not explicitly state when to use this tool vs alternatives, nor does it mention any 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 declare readOnlyHint: true, so the description doesn't need to restate that. It adds value by disclosing pagination behavior and how to fetch subsequent pages, which goes 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the purpose and then providing essential pagination 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 100% parameter coverage, the description adequately covers what an agent needs to know: the resource type, pagination mechanism, and the fact that results are filtered by the provided parameters. It could mention filtering options, but those are in the 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 coverage is 100% with descriptive parameter names and descriptions. The tool description does not add additional meaning beyond the schema, which is acceptable for a list operation. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists FPE tweaks for the organization, with a specific verb and resource. It distinguishes itself from siblings like create_tweak or get_tweak by indicating a listing 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 includes pagination instructions but does not explicitly guide when to use this tool versus alternatives like get_tweak or create_tweak. No when-not-to-use or alternative tool mentions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that rotation doesn't change underlying encryption material, but doesn't mention side effects like whether the old envelope key is retired or if the operation is reversible. Slightly incomplete for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a usage directive, all relevant and front-loaded. No filler or redundancy. 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?
Given the tool has an output schema (not shown) and is a focused operation, the description is mostly complete. It could mention return value type or prerequisites (e.g., key must exist), but overall adequate for a single-purpose tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters (namespace, name, sequence). The description adds no additional parameter-level semantics beyond what the schema already provides, earning a baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Rotate the envelope key for a specific FPE key version.' It explains what envelope rotation does (re-wraps data key without changing encryption material) and distinguishes from siblings like create_key or deactivate_key.
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 explicitly says 'Use this for key rotation compliance requirements,' providing clear context for when to use. It doesn't explicitly state when not to use or name alternatives, but the unique verb 'rotate' among siblings makes it implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses the async nature, token-based retrieval, wait parameter behavior, and the one-week time range constraint. Missing auth requirements or rate limits, but overall informative.
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 four sentences, front-loading the core purpose. No fluff or redundant information. Efficiently communicates key behaviors.
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 complexity (6 parameters, async, output schema exists), the description covers the essential workflow: initiating query, token retrieval, wait behavior, and time constraints. It's complete enough for an AI agent, though could mention pagination via offset/limit, but that's in 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 coverage is 100%, so parameters are already well-documented. The description adds value by noting the one-week max time range and the behavior of 'wait' parameter. However, it doesn't add meaning beyond what's in the schema for most 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 'Search ALTR platform system audits' and distinguishes this tool from other audit searches by specifying it's for system audits and describing the async nature. This differentiates it from sibling tools like search_audits and search_query_audits.
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 explains the async workflow and wait parameter behavior but does not explicitly state when to use this tool versus alternatives. It implies usage for system audits but lacks explicit 'when to use' or '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?
Since no annotations are provided, the description must disclose behavioral traits. It states the replacement behavior, which is non-obvious from the schema alone. However, it omits other potential effects like validation or impacts on active reports.
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 succinct sentences. The first states the purpose, and the second clarifies the behavioral constraint. No unnecessary words are present.
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 complexity of 11 parameters and an output schema, the description is minimal but adequately highlights the key behavioral aspect (full replacement). It does not describe return values, but the output schema exists to cover that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage and provides detailed parameter descriptions (including cron examples and JSON shape). The tool description adds no extra meaning beyond what the schema already conveys, justifying the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing audit report definition and specifies that it is a full replacement. This effectively distinguishes it from sibling tools like create_report_definition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly notes that the operation is a full replacement and that all fields to be preserved must be included. This provides clear guidance, though it could be improved by mentioning cases where partial updates are not supported via 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?
The annotation 'readOnlyHint: true' already indicates a safe read operation. The description adds no extra behavioral details beyond what the annotation provides. With annotations, a baseline of 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the key action and resource. 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?
Given an output schema exists, the description does not need to explain return values. The description sufficiently covers the tool's purpose and scope for a simple get 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?
Schema coverage is 100% and the schema already describes the parameter as 'Access request ID (UUID)'. The description does not add any additional meaning or context, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'get' and the resource 'details for a specific access request'. It distinguishes from sibling tool 'get_access_requests' (plural), which lists requests. The specificity of 'specific access request' indicates singular retrieval.
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 implicitly indicates use for retrieving a single request, but does not explicitly state when to use this vs. other related tools like 'approve_access_request' or 'get_access_requests'. However, given the simplicity, context is mostly 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?
The annotation 'readOnlyHint: true' already indicates a read operation. The description adds value by disclosing that a 202 response means the search is still processing and that retrying is necessary. This behavioral nuance goes 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, consisting of two sentences with no unnecessary words. It is front-loaded with the core purpose and includes important behavioral notes. However, a slightly more structured format (e.g., bullet points) 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?
The tool has an output schema (indicated in context) and all parameters are well-documented. The description covers the retry behavior and implicitly ties to a preceding search. It could mention that this is for general audit results, but the sibling tools help distinguish that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all three parameters (search_uuid, limit, next_page_token) already described clearly in the schema. The description does not add any additional meaning or context for these parameters, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get results from a previously triggered audit search,' specifying the verb (Get) and resource (results from audit search). This distinguishes it from sibling tools such as 'search_audits' (which triggers the search) and 'get_query_audit_results' / 'get_system_audit_results' (which target different audit types).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on when to use the tool (after triggering a search) and what to do if results are not ready (retry after a 202 response). However, it does not explicitly state when not to use it or mention alternatives, leaving some ambiguity.
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 (readOnlyHint true). The description adds valuable behavioral context: it lists the specific fields returned (tag, policy ID, rule count) and provides a detailed reference of 10 masking levels with their meanings. This explains the output beyond what the schema may indicate. 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 well-structured: it starts with the main purpose, then lists return fields, provides usage guidance, and includes a helpful reference. It is moderately long but every sentence adds value. However, the masking levels list could potentially be shortened or linked to documentation, but it is comprehensive and justifies its length.
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 (list with one optional parameter, output schema exists), the description covers the essential aspects: purpose, return fields, parameter use, and downstream usage. It does not address error handling or performance characteristics, but for a read-only list tool this is acceptable. The description is complete enough for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (the single optional parameter 'policy_type' is fully described in the schema). The description does not add additional semantic value for the parameter beyond what is in the schema. The masking levels reference is about return values, not parameter semantics. According to the rubric, with high coverage baseline is 3, and the description does not exceed 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 masking policies configured in your ALTR organization', specifying the verb (List), resource (masking policies), and scope (in your ALTR organization). It also identifies the returned fields (tag, policy ID, rule count) and explains how to use the output with related tools (add_rules, get_rules, delete_policy), providing clear differentiation from siblings like get_rules and create_policy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear usage context: use when you need to list masking policies. It also provides guidance on using the results with other tools. However, it does not explicitly mention when not to use this tool or suggest alternatives (e.g., get_tags or get_databases) for other listing needs. The sibling list is large, so a brief exclusion would improve clarity.
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=true, and the description adds pagination and ordering behavior (creation time descending), which is helpful 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the purpose, then pagination details. 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?
Given the presence of an output schema and full parameter descriptions in the schema, the description sufficiently covers the tool's behavior and pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description mentions 'cursor' for pagination but adds little 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?
Clearly states 'List audit report definitions' with a specific verb and resource, and it is distinct from sibling tools like get_report_definition, create_report_definition, and update_report_definition.
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 pagination guidance using cursor, but lacks explicit context on when to use this tool versus alternative listing or search tools available among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It states the database is set to 'in progress' until the status check completes, disclosing state mutation and asynchronous behavior. With no annotations, this is sufficient though it could detail 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no extraneous words; action is front-loaded in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, output schema present), the description fully explains the effect and next steps, making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description repeats the schema's parameter description exactly, adding no new 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 uses specific verbs 'trigger' and 'sets', and clearly identifies the resource as 'database status sync'. It distinguishes from sibling tools like create_database or update_database by its action of initiating a sync.
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 advises using get_databases afterward to see updated status, providing a clear workflow hint. However, it does not mention when not to use this tool or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool 'Replaces' all three fields, implying overwrite behavior, but does not disclose potential side effects, authorization requirements, or whether it's idempotent. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first clearly states the purpose, the second explains what is replaced and provides a helpful reference. No wasted words; highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is straightforward with 4 parameters and an output schema. The description covers the core operation and directs to the create tool for rule format. No significant gaps given the 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 already covers 100% of parameters, so baseline is 3. The description adds value by referencing create_snowflake_access_policy for the rule format, which helps clarify the structure of the 'rules' parameter beyond the schema's type definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'Update' and the resource 'existing Snowflake access management policy', and specifies that it replaces name, description, and rules. It distinguishes itself from the sibling create tool by focusing on 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 by stating it updates an existing policy, but does not explicitly state when to use or when to avoid. It references create_snowflake_access_policy for rule format, which provides some guidance, but lacks exclusions 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?
No annotations are provided, so the description carries the burden. It describes the creation action and grouping behavior, but doesn't disclose permissions, side effects, or reversibility. It's adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise, with a clear purpose statement, explanation of the collection, and a typical workflow. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description doesn't need to explain return values. It provides workflow context and integrates with sibling tools well. Minor gap in not describing permission requirements or destruction behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds minimal extra meaning beyond the schema, e.g., 'Unique name' slightly clarifies uniqueness, but doesn't elaborate on format 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 the tool creates a classifier collection for automated data discovery, distinguishing it from sibling tools like add_classifiers_to_collection and create_job by placing it in a typical workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly outlines a typical workflow: create a collection (or use existing ALTR Managed), then use in create_job, then review with get_classification_report. This provides clear when-to-use and alternative 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?
With no annotations, the description bears full burden. It discloses creation of a connection and two auth modes, but does not discuss idempotency, overwrite behavior, or side effects. Sufficient for basic usage but lacks depth for a creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two short paragraphs, uses numbered list for auth modes, and front-loads the main action. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers essential aspects: purpose, auth options, and post-creation step. Lacks explicit guidance on mutual exclusivity of password vs. service user fields, but that is inferable from schema. With output schema present, return values need not be explained. Adequate for an agent to operate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by grouping parameters into auth modes (service user vs. password) and indicating that 'service_user_id' comes from 'get_service_users'. This contextualizes parameter relationships beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool connects a Databricks workspace to the ALTR platform, with specific verb 'Connect'. It distinguishes from sibling tools like 'create_databricks_job' or 'create_database' by focusing on the connection setup.
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?
Provides clear context on when to use (to connect a Databricks workspace) and recommends a preferred auth mode. Includes a follow-up step to use 'get_databases' to confirm creation. Does not explicitly state when not to use or list alternatives, but the context is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It explains that the tool runs asynchronously, requires polling, and performs a catalog scan. It does not mention potential limitations or error states, but the async behavior and outcome are well-communicated.
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 sentences long, each serving a distinct purpose: stating the action, detailing the scan, and explaining the async workflow. No redundant information, and the most important elements are 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 tool has a single parameter and an output schema, the description covers the essential aspects: purpose, async behavior, and follow-up tools. It does not discuss error handling or edge cases, but for a straightforward creation tool, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, database_id, has 100% schema description coverage. The tool description does not add additional details beyond what the schema provides, but it correctly integrates the parameter into the overall task. A score of 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool runs a GDLP classification scan on a Databricks database, specifying the verb 'Run', the resource 'Databricks database', and the action 'scan to identify sensitive data columns'. It distinguishes itself from siblings like 'create_job' and 'create_databricks_database' by being specific to classification scans.
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 indicates when to use the tool (to run a classification scan) and provides clear follow-up steps: use 'get_jobs' to poll and 'get_classification_report' to view results. It does not explicitly state when not to use it or list alternatives, but the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses creation (write) and credential constraint, but no annotations exist. Lacks details on idempotency, conflict behavior, or side effects. Output schema exists but not referenced.
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, no wasted words. Purpose and key constraint 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?
Covers essential info for a simple creation tool with 4 params. Output schema exists, so return values need not be explained. Could mention idempotency but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds value by clarifying the 'exactly one' constraint for credential parameters, which is not in 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?
Clearly states verb 'Create' and resource 'repo user', with explicit constraint about credential reference. Distinguishes from siblings like create_sc_repo and create_sc_service_user.
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?
Provides explicit guidance on mutual exclusivity of credential methods ('Provide exactly one of...'). Lacks guidance on when to use this over alternative tools like create_sc_service_user.
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 destructiveHint annotation, the description adds that deactivated tweaks are prevented from use in new FPE operations, clarifying the behavioral impact. No contradiction with annotations found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no unnecessary words. The action is stated first, followed by a key consequence and a helpful pointer. Highly efficient and 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 state-change tool with two parameters and an output schema, the description covers the purpose, consequence, and parameter discovery. It lacks details on return values or authorization, but the output schema mitigates the former.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, so parameters are already well-described. The description adds no new parameter details beyond referencing 'get_tweak' for the sequence identifier, but this does not enhance the semantic understanding of the parameters themselves.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'Deactivate' and the resource 'specific version of an FPE tweak'. It distinguishes from sibling tools like 'delete_tweak' and 'deactivate_key' by specifying the exact resource and action.
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 that deactivated tweaks cannot be used for new FPE operations, providing consequence. It also explicitly advises using 'get_tweak' to discover the sequence identifier, guiding the agent on parameter acquisition.
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 confirm destructiveHint=true; the description adds the precondition about task_count, indicating that deletion will fail if not met, but does not detail other side effects or irreversibility 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?
One concise sentence front-loading the action and including the precondition, 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 the output schema likely handles return values, the description covers the core action and precondition adequately; could mention if deletion is reversible or cascades, but not necessary for this simple case.
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 already describes agent_id as 'Agent UUID' with 100% coverage; description adds no further parameter meaning beyond the precondition regarding 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 description clearly states 'Delete an agent' with a specific verb and resource, distinguishing it from sibling tools like delete_sc_agent_task.
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 precondition 'Agent must have task_count of 0' tells when to use the tool, implicitly guiding away from agents with tasks, but does not explicitly list alternatives 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?
The description adds the precondition about listeners beyond the destructiveHint annotation, which informs the agent of a necessary condition for successful execution.
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, front-loading the action and then the condition, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool, the description adequately covers the action and a key precondition. It does not discuss error handling or output, 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes the single parameter 'sidecar_id' as 'Sidecar UUID.' The description adds no additional parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a sidecar,' which is a specific verb and resource, and it is distinct from sibling tools like create_sc_sidecar and get_sc_sidecar.
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 condition 'Must have no listeners' provides clear context for when the tool can be used, but it does not explicitly state when not to use it or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations set readOnlyHint=true, and the description's 'List running instances' aligns with read-only behavior. The description adds 'running' which implies a status filter, 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?
Single sentence of 7 words, no fluff. Every word is meaningful and front-loaded with verb and resource. Excellent 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?
Description is minimal but sufficient given an output schema exists and parameters are well-documented. Could mention pagination via contiguous_id, but that is covered in schema. Overall complete for a 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 coverage is 100%, so all parameters are documented in the schema. The description does not add extra meaning beyond the schema. 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?
Description clearly states 'List running instances for a specific ALTR agent', specifying the verb 'list', resource 'running instances', and scope 'for a specific ALTR agent'. This distinguishes it from siblings like 'get_agent_instance' (single) and 'delete_agent_instance'.
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 explicitly states the tool is for listing instances for a specific agent, which implies when to use it (when you need all instances of an agent) versus get_agent_instance (single). However, it does not provide explicit when-not-to-use or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read-only. Description adds that it returns the latest version by default and can retrieve historical versions with sequence, providing valuable behavioral context 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with main purpose, no unnecessary words. Efficiently communicates key functionality.
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?
Sufficient for a simple retrieval tool with output schema. Covers primary and historical retrieval. No mention of errors or limits, but not critical for this 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?
Schema coverage is 100%, so parameters are already described. Description adds meaning for 'sequence' (retrieve historical version), augmenting the schema. No additional info for namespace/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?
Description clearly states it retrieves a single FPE key by namespace and name, distinguishing it from list_keys or other tools. Mentions ability to get historical versions via sequence.
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 context for when to use (retrieve single key) but does not explicitly state when not to use or mention alternatives like list_keys. Adequate but could be more explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds behavioral detail about pagination using contiguous_id, which is 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with two sentences that front-load the main purpose and then add pagination details. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of many sibling tools, the description covers essential aspects (pagination, namespace) for a list operation. It does not describe filtering options, but those are in the schema. The output schema exists separately, so it is not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining how to use contiguous_id for pagination and noting the fpe namespace as common, which goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists FPE keys within a namespace, specifying the resource (keys) and action (list). It distinguishes itself from related tools like get_key by focusing on listing multiple keys, and includes the context of pagination and common namespace.
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 clear context on when to use this tool (listing FPE keys), but does not explicitly state when not to use it or provide alternatives like get_key for individual keys. The pagination hint offers some 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 declare readOnlyHint=true, and the description adds ordering detail (newest-first) and clarifies each instance is a generated report. 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, front-loaded with the purpose, no 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?
With output schema present, return values are covered. Description adds ordering and implies pagination via parameters. Could mention pagination explicitly, but sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds no new meaning beyond reinforcing that definition_id is required. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (List) and resource (report instances for a given definition). It distinguishes from sibling tools like get_report_instance (single instance) and list_report_definitions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies usage with a required definition_id and mentions ordering (newest-first). It does not explicitly state when to avoid or alternative tools, but the context is clear given 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?
No annotations provided, so description must disclose behaviors. It mentions immediate generation and rate limiting but lacks details on permissions, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences free of clutter, front-loading the core purpose and adding essential detail without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Has output schema (not shown), so return values are handled. Description covers core behavior and rate limiting; missing only minor aspects like prerequisites or error scenarios.
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?
Only one parameter (definition_id) with clear schema description. Description adds context about per-definition rate limiting, enhancing parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 it triggers an on-demand audit report, distinguishes from siblings like create_report_definition or archive_report_definition by focusing on triggering an existing definition outside schedule.
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?
Implicitly indicates when to use: when an immediate report is needed outside schedule. Includes rate limit but no explicit when-not or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description adds critical behavioral details: permanent deletion, inability to detokenize, deterministic token re-generation behavior, rate limits (492/month, 50/second), and maximum 4096 values per call. This fully informs 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise: three sentences covering purpose, behavioral impact, and constraints. No redundant information, and the most important action is stated first.
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 the destructive annotation, the description covers the essential behavior, limitations, and usage constraints. It could optionally mention that the output schema provides deletion results, but it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents the 'tokens' parameter as a dict. The description does not add additional meaning beyond what's in the schema description, leading to a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'delete' and the resource 'vault tokens', specifying it is permanent. It distinguishes from siblings like vault_tokenize and vault_detokenize by focusing on deletion rather than tokenization or detokenization.
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 context (permanent deletion, re-tokenization behavior) but does not explicitly state when to use this tool versus alternatives (e.g., critical_delete_tokens). No usage exclusions or comparisons to siblings 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?
No annotations provided, so description carries burden. It discloses asynchronous behavior (10-30+ minutes) and recommends polling. Could mention read-only nature, but still informative.
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 paragraphs, front-loaded with main purpose. No filler. Every sentence adds value.
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?
Covers purpose, async behavior, follow-up tools. Output schema exists, so return values need not be explained. Complete for a 3-param tool with no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; description adds little beyond schema for parameters (e.g., 'classifiers in the specified collection' for collection_name). Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it runs an automated classification scan to discover sensitive data. It specifies the resource (database) and action (scan), and differentiates from siblings like create_classifier and create_database.
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?
Provides clear context: scans database columns using classifiers in a collection. Mentions asynchronous nature and suggests follow-up tools (get_jobs, get_classification_report). Does not explicitly exclude alternatives, but guidance is adequate.
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, but description adds valuable context: invalid tokens are silently ignored, deterministic token re-tokenization behavior, and a maximum of 1024 values per call. This goes beyond the annotation to disclose important operational details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with three clear points in separate paragraphs. No unnecessary words. Front-loaded with the primary action, then key behaviors. Every sentence adds value.
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 delete operation, the description covers what happens (delete), edge cases (invalid tokens, re-tokenization), and limits (1024). Output schema exists, so return format is not needed. Complete for effective invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and describes the 'tokens' parameter as a dict. Description adds a usage example and the constraint of max 1024 values, which complements the schema. The description enhances understanding of the parameter's 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 'Delete critical tokens, removing them from the token store.' It specifies the resource (critical tokens) and action (delete), and distinguishes from sibling delete tools like 'vault_delete_tokens' by the 'critical' qualifier and additional behavior details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool over alternatives like 'vault_delete_tokens'. It implies use for critical tokens but lacks direct comparison or exclusion criteria. The behavior details (silent ignore, re-tokenization) provide some context but no when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description explains that deactivated keys cannot be used for new encryption operations, adding valuable 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?
Two sentences, front-loaded with the action, 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?
For a simple deactivation tool with annotations and output schema, the description provides essential context: the effect and a tip for obtaining the required parameter. 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?
Input schema has 100% description coverage for all three parameters. The description adds no additional parameter information 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?
Description clearly states the tool deactivates a specific version of an FPE key, and explains the consequence. This distinguishes it from siblings like deactivate_tweak or rotate_key.
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?
Provides guidance to use get_key to find the sequence identifier, which is a prerequisite. Does not explicitly mention when not to use, 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 signal destructiveness with destructiveHint=true. The description adds valuable behavioral context: constraints on deletion (only if not in use by active/recent jobs, only own collections). 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?
Extremely concise: three sentences that cover purpose and constraints without any fluff. First sentence directly states the action, making it front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and an output schema, the description is complete. It explains the action, the conditions for use, and the parameter's source. No additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for collection_name ('Exact collection name as returned by get_collections'). The description does not add extra parameter semantics beyond what the schema provides, so 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?
Description clearly states 'Delete a classifier collection', specifying the action and resource. The constraints (cannot delete if in use by active/recent jobs, only delete collections you created) further clarify its scope, distinguishing it from sibling tools like delete_classifier.
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?
Description provides explicit when-to-use guidance ('only delete collections you created that are no longer needed') and when-not-to-use ('Cannot delete collections that are in use by active or recent jobs'). While it doesn't name alternative tools, the context is clear enough for appropriate 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 indicate destructiveHint=true. Description adds context about removal of all associated rules and a safe usage suggestion (review first), which goes 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action, then caution and guidance. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter and existing output schema, the description covers purpose, scope, and caution adequately. No 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?
Only one parameter, policy_id, is fully documented in the schema with clear instructions. Description does not add additional meaning beyond what the schema provides, 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 'Delete a masking policy and all its rules,' specifying the action and scope. It distinguishes from siblings like 'delete_rule' which deletes a single rule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises 'Use with caution' and recommends reviewing rules with `get_rules` first. Provides clear when-to-use guidance but lacks explicit alternatives 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=true, so description doesn't need to repeat that. Description adds that it returns metadata with database names and IDs, but no behavioral traits beyond what annotations cover. 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 key purpose, no extraneous information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, and description sufficiently explains the return (database names and IDs). For a simple, parameterless listing tool, this is complete and adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters, and schema description coverage is 100%. Description adds meaning by specifying that it returns database names and IDs, which is useful context. 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?
Description clearly states the tool discovers Snowflake databases connected to ALTR, with a specific verb ('Discover') and resource ('databases'). It distinguishes from sibling 'get_database_id' by noting the sibling provides the numeric ID for classification jobs.
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?
Description gives context for when to use this tool (to discover databases) and when to use an alternative ('get_database_id' for numeric ID). It implicitly suggests this tool for listing, but doesn't explicitly state exclusionary conditions.
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 annotation readOnlyHint=true already indicates the tool is non-destructive. The description adds value by specifying the return content (masking configuration, status, timestamps) and platform constraints (Snowflake only, no Databricks support). 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 three sentences, directly addressing purpose, scope, and usage. It is front-loaded with the core action and avoids unnecessary detail. Every sentence serves a purpose.
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 presence of an output schema explaining return values, the description sufficiently covers platform limitations, usage context, and what the tool returns. There are no gaps for a read-only tool with comprehensive schema information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so baseline is 3. The description does not add significant meaning beyond what the schema already provides; it only mentions 'by database, tag, and schema' which is already clear from the schema. The optional protection_type parameter is not discussed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 full details for a specific tag masking, specifies the platform (Snowflake only), and lists what is returned (masking configuration, status, timestamps). It also distinguishes itself from get_tag_details_by_group_id by noting the use of database/schema/tag instead of group_id.
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 explicitly says when to use this tool ('when you know the exact database/schema/tag but not the tag_group_id'), and notes a platform limitation (Snowflake only, Databricks tags not supported). It implicitly points to an alternative (get_tag_details_by_group_id) but does not explicitly mention 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?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It reveals key behaviors: pinning is conditional on sign-off and mutually exclusive (only one pinned comment per instance). It does not detail error handling if a pin already exists, but the constraints are transparent enough for the agent to infer outcomes.
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 sentences, front-loaded with the core action. Every sentence serves a purpose: first states the operation, second provides critical constraints. No unnecessary words or repetition.
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 existence of an output schema (not shown, but indicated), the description does not need to explain return values. It covers the essential behavior: pinning a comment, the single-pin constraint, and the prerequisite condition (sign-off). For a simple CRUD-like tool, this is 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 100% coverage with descriptions for all three parameters. The tool description merely restates the general action without adding parameter-specific meaning beyond what the schema already provides. Therefore, it adds minimal semantic value beyond the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Pin a comment') and the resource ('on a report instance'). It distinguishes from sibling tools like unpin_report_comment and create_report_comment by implying pinning as a distinct operation. The constraint of 'only one per instance' further clarifies its unique role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides critical usage context: pinning is only allowed after sign-off and only one comment can be pinned at a time. It implicitly guides the user to consider unpinning if needed, though it doesn't explicitly list alternatives or when not to use. This is sufficient for a straightforward tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While the destructiveHint annotation already indicates destructive behavior, the description adds important behavioral details: the tool cannot delete ALTR managed classifiers, and it is restricted to user-created classifiers. This provides context 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise, consisting of two short sentences. It front-loads the primary purpose and immediately follows with usage restrictions, 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 is simple (one parameter, destructive), and the description covers purpose and usage restrictions. An output schema exists, so return values are not needed in the description. The description adequately addresses the tool's scope without missing critical 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 input schema already fully describes the single parameter (classifier_name) with a clear description. The tool description adds no additional parameter semantics, so the baseline score of 3 applies given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool removes a custom classifier, using the verb 'Remove' and specifying the resource 'custom classifier you created'. It distinguishes itself from other delete tools by clarifying it only applies to user-created classifiers, not ALTR managed ones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('Only use for classifiers you created with `create_classifier`') and when not to use it ('Cannot delete ALTR managed classifiers'), providing clear guidance on appropriate contexts.
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, description adds platform restriction (Snowflake only) and alternative for Databricks. 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?
Three concise sentences: action, platform constraint, sibling differentiation. No 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?
Covers purpose, usage context, platform specificity, and alternatives. Output schema present, so return values are covered. Lacks mention of error handling or prerequisites, but given destructiveHint and clarity, it's sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. Description does not add extra parameter-level detail beyond schema, which is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states action: delete tag masking by database, schema, and tag name. Differentiates from sibling tools delete_tag (alternative) and delete_policy (for Databricks).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: when tag_group_id is unknown but database/schema/tag details are known. Also states when not to use: for Databricks, use delete_policy instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X 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 the description adds minimal behavioral context beyond stating it lists collections. It does not contradict annotations but also does not elaborate on pagination 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with a line break, concise and front-loaded with purpose. Slightly informal line break, but 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?
Given the output schema exists, the description completes the context by defining collections and their role in classification jobs. Sufficient for a list 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, so the input schema fully covers them. The description does not need to add parameter information; baseline 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists classifier collections, defining them as groups of classifiers for classification jobs. It differentiates from sibling tools like create_collection and delete_collection by specifying the listing action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use: before creating a classification job to check for existing collections (e.g., 'ALTR Managed') to avoid duplicates. Implicitly indicates not to use for creation or modification.
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 indicates a read-only operation ('List'), consistent with the readOnlyHint annotation. It adds behavioral context by explaining that the returned service user IDs are needed for create_database, going 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 two sentences, front-loaded with the main action, and each sentence adds valuable information without redundancy. Highly concise and structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (no parameters, clear output as IDs), the description is largely complete. It could mention other output fields if present, but the context signals indicate an output schema exists, so the description suffices.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the description naturally covers parameter semantics by requiring none. Per guidelines, a baseline of 4 is appropriate since no additional parameter information 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 verb 'list' and resource 'Snowflake service users', specifies their purpose for database connections, and distinguishes itself by noting the use case with keypair authentication for create_database, differentiating from sibling tools like get_sc_service_user.
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 explicitly states when to use the tool: when setting up a Snowflake database with keypair authentication. It provides a clear context but does not mention when not to use it or alternatives, which slightly reduces the score.
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?
No annotations provided, so description carries full burden. Discloses that update is partial (only provided fields) and non-destructive (no delete/recreate). Does not mention permissions or rate limits, but covers key behavioral aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then usage tips, then a comprehensive but necessary mapping for masking levels. The list could be slightly trimmed but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (return values covered), the description complements it well with preconditions, partial update behavior, and parameter reference. 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?
Schema coverage is 100%, but description adds value by explaining the meaning of masking level codes (10000-10009), which the schema only labels. This goes beyond the schema's 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 'Update' and the resource 'existing masking rule', and distinguishes itself from siblings like delete_rule and add_rules by specifying 'without deleting and recreating it'.
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?
Provides clear guidelines: only provided fields update, omitted fields unchanged, and advises using get_rules first to find rule_id and current values. Does not explicitly state when not to use, but context is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, description carries full burden. It states the operation is an update (implying mutation) and Snowflake-only constraint. However, it lacks details on idempotency, permissions, error states, or side effects beyond the basic operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise paragraphs: first states purpose and Snowflake-only restriction, second provides usage hint and sibling tool. Front-loaded, no redundant 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?
Covers Snowflake-only constraint, prerequisites, and sibling differentiation. Missing explicit mention of success/response, but output schema exists (per context) so not required. Adequately complete given tool 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?
Schema coverage is 100% so baseline 3. Description adds value by guiding use of get_tags for tag_group_id and framing parameters as masking configuration. This extra context elevates the score to 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 updates a tag connection's masking configuration, specifies the resource (tag connection), and distinguishes it from connect_tag (for new tags). It also mentions Snowflake-only scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states Snowflake-only usage, explains Databricks tags are not supported and directs to policy/rules instead. Provides prerequisite (use get_tags) and links to connect_tag for new tags, giving clear when-to-use and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses key behavioral constraints: required existence, uniqueness, and special handling for ALTR collections; output schema exists so return values need not be described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise, front-loaded sentences 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?
Fully covers the tool's preconditions and constraints; with output schema present, no further details are needed.
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?
Adds meaning beyond schema by stating that classifiers must already exist and not be duplicates, complementing the schema's type descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (add) and the resource (classifiers to an existing collection), distinguishing it from siblings like remove_classifiers_from_collection.
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?
Provides specific preconditions (classifiers must exist, not already in collection) and an exclusion (ALTR managed collections cannot be appended), but does not explicitly name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that archiving is a soft-delete, that definitions become hidden from normal listings, and that restoration is possible via a sibling tool. This adds value beyond the destructiveHint annotation, which only indicates potential data loss.
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. Front-loaded with the core action and immediately clarifies soft-delete 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?
Complete for a single-parameter tool with output schema. Covers behavior, visibility, and recovery path.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with the parameter description already clear. The description does not add additional semantics but is sufficient given the simplicity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 the tool archives (soft-deletes) an audit report definition, distinguishing it from related tools like restore_report_definition. The verb 'archive' and resource 'audit report definition' are specific and accurate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to use (to hide from listings without permanent deletion) and mentions the alternative tool for restoration. Could be slightly improved by contrasting with permanent deletion, but it is effective.
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?
No annotations are provided, so the description carries the full burden. It discloses that the tool creates a database connection, lists authentication options, and recommends verification. It does not mention potential errors or permissions but provides sufficient behavioral context for a creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with a clear opening sentence followed by bullet points for authentication modes. Every sentence adds value, and there is no redundancy or 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 8 parameters and an output schema, the description covers authentication modes and post-creation steps. It could mention what happens on failure or required permissions, but it is adequate for a creation tool among many siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant value by grouping parameters into two authentication modes, explaining that 'service_user_id' comes from 'get_service_users', and clarifying that hostname/port are only for password auth. This guidance is not evident from schema descriptions 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 'Connect a new data source to the ALTR platform' with a specific verb and resource. It distinguishes from siblings like 'create_databricks_database' by focusing on generic database creation and detailing two authentication modes.
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 two authentication modes with conditions and suggests using 'get_databases' post-creation. However, it does not explicitly exclude use cases or compare to alternative tools like 'create_databricks_database'.
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. Description adds value by explaining fine-grained nature and prerequisite step, 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?
Three concise sentences covering purpose, benefit, and prerequisite. 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?
Given simple 2-param tool with output schema, description covers purpose, usage, and prerequisite. Complete for intended use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions are already complete (100% coverage). Description adds context on how to obtain rule_id parameter, which is helpful beyond 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?
States 'Remove a specific masking rule from a policy' with clear verb and resource. Differentiates from delete_policy by explicitly noting 'without deleting the entire policy'.
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?
Provides explicit prerequisite: 'Use get_rules first to identify the rule_id'. Does not explicitly state when not to use, but context implies deletion of entire policy is 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=true, so the description adds value by detailing the output (sensitive column detection with confidence scores) and the job completion precondition. 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?
Description is concise and well-structured: purpose, output, precondition, follow-up steps. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and the tool's simplicity (one parameter, read-only), the description covers all necessary context: precondition, output nature, and workflow integration. Complete for agent selection.
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 (job_id) with 100% schema description coverage. Description does not add further parameter details beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves detailed results from a completed classification job, specifying columns with sensitive data and confidence scores. It distinguishes from sibling tools like get_jobs and get_tags by mentioning the precondition and subsequent steps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to call only after job completion (verified via get_jobs) and provides a workflow: after review, check tags with get_tags and create if missing. This gives clear when-to-use and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds value by specifying the types of classifiers (ALTR-managed and custom) and giving examples. 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 three concise sentences, front-loaded with the main action, then explanatory context. 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?
Given no parameters, a read-only annotation, and an output schema present, the description sufficiently covers the tool's purpose and scope. It explains what classifiers are and that both managed and custom are included.
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 does not need to add parameter details. It correctly achieves baseline 4 per rubric.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all available data classifiers and explains what they are (pattern-based detectors for sensitive data types). It implicitly distinguishes from sibling tools like create_classifier or delete_classifier by focusing on listing.
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 usage is clear from the description: use this to get a list of classifiers. However, there is no explicit guidance on when to use this vs alternatives like get_collections or create_classifier, but the purpose is straightforward enough.
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, so the agent knows it's a safe read. The description adds context that the ID is numeric and required for jobs, which is helpful 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences plus a workflow note. Every sentence adds value: core function, necessity, and context. No fluff or repetition.
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 low complexity (single parameter, read-only, output schema exists), the description fully covers the tool's purpose, workflow position, and relationship to sibling tools. The output schema handles return details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (the only parameter 'database_name' is described in the schema). The tool description does not add additional details about the parameter beyond 'for a database name,' so it meets the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Get the ALTR database ID for a database name.' Identifies the specific resource (database ID) and action (get). Differentiates from siblings like 'get_databases' by positioning it in the workflow: after identifying databases, before creating jobs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Required before creating classification jobs' and provides a typical workflow: 'After identifying your database with `get_databases`, call this to get the ID needed for `create_job`.' This tells the agent when to use it and references alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide `readOnlyHint: true`, so safety is clear. The description adds important behavioral context: jobs are asynchronous and take 10-30+ minutes. This is valuable beyond the annotation. 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 concise and well-structured. It starts with the core purpose, then gives typical workflow and timing. Every sentence adds value, and the structure aids quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (async job monitoring) and the presence of a complete input schema and output schema (mentioned implicitly), the description covers all necessary context: async nature, timing, workflow integration, and the next step.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema itself fully documents all 7 parameters. The description does not need to add parameter details; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Check the status of classification jobs you've run.' It distinguishes itself from the sibling `get_classification_report` by explaining that this tool is for checking job status, and the report is fetched only after completion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: after creating a job, wait 15-30+ minutes, then use this function. It also tells what to do when status is COMPLETED (use `get_classification_report`) and when still RUNNING (wait longer). No misleading advice.
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. The description adds asynchronous behavior (202 response, retry) beyond annotations, but does not cover potential rate limits or failure modes.
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 six lines, front-loaded with purpose, and every sentence adds value. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a polling tool with pagination and an output schema, the description covers async behavior, pagination token, and sibling differentiation. It is complete given the schema richness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds context for 'search_uuid' linking it to search_query_audits, but does not elaborate on 'limit' or 'next_page_token' beyond 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 'Get results from a previously triggered query audit search' with a specific verb and resource. It distinguishes from sibling 'get_audit_results' by explicitly mentioning 'For sidecar audit results, use get_audit_results instead.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use (after search_query_audits), when not to use (for sidecar), and provides guidance on handling 202 responses with retry logic.
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=true, so the tool is safe. The description adds value by explaining that roles are used in add_rules and that it lists all roles, which is behavioral context 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences. Each sentence adds value: first states the primary function, second explains how the output is used elsewhere. 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?
Given the tool has no parameters and an output schema exists (though not shown), the description is complete for a list operation. It explains the purpose and usage in the broader workflow, leaving no gaps.
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 schema coverage is 100%. The description does not need to add parameter information, and its absence is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all ALTR roles, which are user groups. It distinguishes itself from siblings like get_rules by explicitly mentioning roles are used in add_rules, providing specific context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: to list roles for use in add_rules. It provides a clear usage context but does not explicitly state when not to use it or name alternative tools, though the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adds important behavioral info: auto-split for >99 rules, batch nature, and prerequisite. Lacks details on error handling or idempotency, but sufficient for basic 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 focused paragraphs: first states purpose and prerequisite, second details rules structure and batch limit. 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?
Given sibling tools and output schema existence, the description covers key aspects: operation, constraints, prerequisite, and parameter format. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant meaning beyond schema: 'Raw policy ID from `get_policies`. Do not URL-encode.' and rules explanation (dict structure, alternative JSON string), enhancing agent understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add one or more masking rules'), the resource ('to a policy'), and the batching capability. It distinguishes from 'create_policy' and 'delete_rule' by context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides prerequisite ('A policy must already exist... see `create_policy`') and batch limit. Does not explicitly exclude scenarios for using 'update_rule' or other alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral aspects: it registers a Snowflake tag as a first-class ALTR object, creates a `tag_group_id` and masking configuration, and automatically resolves the friendly database name. It also lists related tools for inspection and editing, giving a complete picture of 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 well-structured: it opens with a clear purpose statement, then provides platform-specific guidance, explains workflow, and ends with a behavioral note. It is reasonably concise, though the Databricks advice is repeated slightly. 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.
Completeness5/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 lack of annotations, the description is complete. It explains the tool's role within the ALTR ecosystem, prerequisites, post-connection effects, and platform-specific behavior. The presence of an output schema (not shown but indicated) complements the description, making it fully informative for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that `database_name` is a friendly name from `get_databases` and that the tool auto-resolves it, but it does not elaborate on `schema_name` or `tag_name` beyond the schema. The added context is useful but not extensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: connecting a Snowflake tag to ALTR for use in masking policies. It specifies the action (connect), the resource (Snowflake tag), and the intended use, effectively distinguishing it from sibling tools by explicitly stating it is Snowflake-only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'SNOWFLAKE ONLY — do NOT use for Databricks.' It explains why Databricks tags are not applicable and directs the agent to use `create_policy` instead. It also outlines prerequisites (tag must exist in Snowflake) and post-connection behavior, making when-to-use and when-not-to-use clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint=true. The description adds significant behavioral details: it passes through non-tokens, does not fail on mixed input, and has a call limit. 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 very concise: one sentence for purpose, one contrasting with sibling, and one for a constraint. Front-loaded with the core action. No extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, constraints, and behavior. Could mention error handling for invalid tokens, but output schema likely provides return type details. Overall sufficient for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and already includes parameter descriptions (e.g., 'Non-token values are passed through'). The tool description only restates this concept without adding new parameter-specific meaning, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool detokenizes critical tokens while passing non-token values through unchanged. It distinguishes itself from sibling 'critical_detokenize' by noting it does not fail on non-tokens, providing a specific 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly contrasts with 'critical_detokenize', telling when to use this tool (when non-token values may be present). Also mentions a maximum of 1024 values per call, providing clear usage constraints.
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, so the read-only nature is clear. The description adds context that these values are used when creating masking rules with `add_rules`, which is helpful. 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 concise, using only three sentences organized into paragraphs. Every sentence adds essential information without 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 description is complete for a simple list tool: purpose, platform restriction, and usage context are covered. The output schema presumably documents return values, so no need to describe them here.
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 covers both parameters with descriptions, achieving 100% coverage. The description adds value by specifying that the tag_name comes from `get_tags`, providing a cross-reference that clarifies parameter sourcing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'allowed values for a specific tag'. It distinguishes from siblings by explicitly noting that this is Snowflake-only, contrasting with Databricks tags which require different handling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'SNOWFLAKE ONLY' and explains why Databricks tags are not applicable, providing clear guidance on when to use the tool and when not. It also references `get_tags` as the source for the tag_name parameter.
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?
No annotations are provided, so the description carries full burden. It discloses that the search is async, returns a search_uuid valid for 30 days, and that results are retrieved via a follow-up call. It does not mention rate limits, authentication needs, or failure modes, but the core async behavior is well explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, using three short paragraphs. Each sentence adds essential information: purpose, async nature, follow-up instruction, filter logic, and sibling differentiation. 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 15 parameters and async nature, the description covers the main workflow and filter semantics. It does not detail error handling or timeout, but with an output schema present (not shown), the return format is presumably documented. The description is sufficient 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter having a description. The description adds valuable context that all filters are combined with AND logic, which clarifies how multiple parameters interact. This goes 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 the tool searches Snowflake query audits specifically for tag and column masking. It uses a specific verb 'Search' and identifies the resource 'Snowflake query audits'. It distinguishes from the sibling tool 'search_audits' by noting that sidecar proxy audits should use that instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool (for Snowflake tag-based or column-based masking audits) and when not to (for sidecar proxy audits, use 'search_audits'). It also explains the async workflow and that all filters combine with AND logic.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It reveals that configuration depends on agent type, explains schedule format, and notes conditional service_user requirements. However, it does not disclose potential side effects, permissions, 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 structured into clear sections and front-loads the main purpose. It is comprehensive but slightly lengthy; every sentence earns its place, though minor trimming could improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 params, conditional logic), the description thoroughly covers all parameters and usage scenarios. An output schema exists, so return values need not be explained. Contextually complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but the description adds significant meaning: it explains the configuration structure per agent type, schedule format, and service_user conditions, far exceeding 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 'Create a task for an agent' and specifies that the task runs against a specific repo on a schedule. It distinguishes from sibling tools like delete_sc_agent_task, update_sc_agent_task, and list_sc_agent_tasks by focusing on creation and configuration details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance, including checking agent type with get_sc_agent first. It details configuration per agent type (CLASSIFIER vs SIS) and specifies fields to include or avoid, serving as clear alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint=true. Description adds that deletion fails if policies remain, and that it applies only to Snowflake tags, 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?
Three sentences, each adding unique value: core purpose, platform guidance, and prerequisite. 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?
Covers all essential aspects: action, platform restriction, prerequisite, and alternative for different platform. Output schema is separate, so return value explanation 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?
Schema coverage is 100% with clear description for tag_group_id. Description does not add additional parameter meaning beyond what schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb (delete), resource (connected Snowflake tag), and scope (from ALTR). Distinguishes from Databricks tags and sibling delete tools like delete_policy via explicit platform restriction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'SNOWFLAKE ONLY' and provides alternative (delete_policy) for Databricks tags. Also states prerequisite that all policies must be removed first, otherwise deletion fails.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses behavioral traits beyond the annotations (readOnlyHint=true). It explains that non-token values are returned as-is, details rate limits (492 requests/month, 50 requests/second), and maximum call size (4096 values). 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 concise (4 sentences) and front-loaded with the core action. Each sentence adds value: main action, comparison to sibling, and operational limits. No superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (single parameter with nested object, rate limits, output schema exists), the description is complete. It explains behavior, use case, limits, and links the sibling tool for comparison.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, with a detailed description for the 'values' parameter including an example. The tool description does not add significant new information about parameter semantics beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: detokenize vault tokens while passing non-token values unchanged. It explicitly distinguishes itself from the sibling tool vault_detokenize, which fails on non-token values.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly compares this tool to vault_detokenize, providing a clear when-to-use scenario: when non-token values may be present. It also includes rate limits and maximum values per call, giving operational constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that until rules are added, all users see NULL for tagged columns. Explains per-platform behavior: Snowflake tags are connected objects, Databricks tags are raw strings. Also warns about policy uniqueness per tag.
Agents need to know what a tool does to the world before 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 long but well-structured with clear sections for purpose, platform differences, and masking levels. It is front-loaded with key information. The masking levels list is necessary reference info, so no waste.
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 complexity with platform differences and no annotations, description covers all necessary aspects: purpose, prerequisites, post-creation steps, parameter nuances, and available masking levels. Output schema exists but doesn't need return value explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds crucial context beyond schema: case-sensitivity for Snowflake tag, requirement for 'policy_type' only for Databricks, 'database_ids' must be a list even for single IDs, and connection prerequisites. This significantly aids correct parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create an empty masking policy for a specific tag' and explains its role controlling data masking. It distinguishes from sibling tools like 'add_rules' and 'get_policies', noting that rules are added later and conflicts should be checked first.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises checking 'get_policies' first to avoid conflicts and using 'add_rules' after creation. Provides platform-specific guidance: for Snowflake, must call 'connect_tag' first; for Databricks, must not call 'connect_tag' and must set 'policy_type' to 'PUSHDOWN' and provide 'database_ids'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the `readOnlyHint` annotation, the description adds important behavioral details: failure on invalid tokens, token format requirements, and limits. There is no contradiction with annotations, and the agent understands both the safety profile and 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only three sentences, each serving a clear purpose: state the action, explain failure and alternative, and provide operational constraints. 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.
Completeness5/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 covers purpose, usage guidelines, parameter semantics, and behavioral aspects comprehensively. It addresses failure modes, limits, and distinguishes from a sibling, making it self-contained 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 input schema already fully describes the parameter with an example. The description adds value by specifying the token format and validation criteria (64+ chars, `token_XXXX...`), which is not in the schema, raising it above the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Detokenize critical tokens to recover plaintext values') and distinguishes this tool from the sibling `critical_partial_detokenize` by specifying that it fails on non-valid tokens, while the partial version handles mixed inputs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises when to use this tool (all tokens are valid critical tokens) and when not (mixed inputs, recommending `critical_partial_detokenize`). It also provides constraints: maximum 1024 values and case-sensitivity, leaving no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, and description adds pagination behavior (token chaining). This exceeds the needed transparency for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no redundancy. Every word adds value.
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?
Output schema exists to cover return values. Description sufficiently explains token usage and pagination for a simple paginated read 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?
Schema has 100% coverage with description for token parameter. Description adds context about pagination usage, improving beyond baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get results from a system audit query', specifying the verb and resource. It distinguishes from sibling tools like search_system_audits (which initiates queries) and get_audit_results/get_query_audit_results (which likely target different audit types).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use the token from search_system_audits and explains pagination handling with moreData flag. No alternatives needed beyond the referenced sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds context: only connected tags appear, tags must be connected via connect_tag, and Snowflake vs Databricks behavior. It fully discloses 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 succinct with three sentences: it states purpose, then provides a key usage boundary, then a detail about connected tags. 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?
Given the low complexity (0 params) and presence of output schema, the description fully covers the tool's purpose, preconditions, and exclusions. It references sibling tools like connect_tag and create_policy 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?
No parameters exist, and schema coverage is 100%. The baseline for 0 params is 4; the description implicitly covers that no input is needed and clarifies what tags are returned.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 Snowflake tags connected to ALTR for use in policies. It explicitly distinguishes itself from Databricks tag handling, providing a specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use (discovering connected Snowflake tags) and when-not-to-use (for Databricks tags, which should be passed directly to create_policy). It also explains the prerequisite of connecting tags via connect_tag.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint: true), description discloses failure behavior, rate limits (492/month, 50/sec), max values (4096), and case sensitivity. Adds substantial context about operational 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?
Four sentences, each purposeful: main action, failure/alternative, rate limits, limits/case sensitivity. Front-loaded with primary purpose, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers error conditions, scaling limits, case sensitivity, and alternative tool. With output schema present, return values are handled. All essential context for correct invocation is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already provides description for 'tokens' parameter (dict mapping keys to tokens). Description adds token format (vaultd_XXXX...), max values, and case sensitivity, enhancing understanding beyond schema 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?
States verb 'Detokenize', resource 'vault tokens', and outcome 'recover plaintext values'. Distinguishes from sibling vault_partial_detokenize by specifying it fails on non-valid tokens, indicating its purpose for pure token inputs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly warns about failure if any token is invalid and directs to vault_partial_detokenize for mixed inputs. Also provides rate limits and maximum batch size, giving clear constraints on usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description adds valuable behavioral context: Snowflake-only, dependency on group ID from get_tags, and returns specific details. 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?
Four sentences, front-loaded with main purpose, no fluff. Each sentence adds essential information: action, constraint, return contents, and prerequisite. Ideal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description doesn't need to detail return format but lists key contents. It covers purpose, limitations (Snowflake only), prerequisite, and return scope, making it fully complete for a read-only detail tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single required parameter 'tag_group_id' is fully described in both schema and description. The description adds context ('Tag group identifier from `get_tags`' and usage instruction), enhancing understanding beyond the schema 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 full details for a specific connected tag by its group ID.' It specifies Snowflake-only, distinguishes from Databricks tags, and lists return contents (masking config, status, database info, timestamps), differentiating from list and other detail tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'SNOWFLAKE ONLY' and that 'tag_group_id only exists for connected Snowflake tags; Databricks tags are raw strings and have no group ID,' indicating when not to use. Also instructs 'Use `get_tags` first to find the tag_group_id,' providing a clear prerequisite and sequence.
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:

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

Score Badge

Copy to your README.md:

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

Latest Blog Posts

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

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/altrsoftware/altr-mcp-server'

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